Plate Basic Elements

Plate Basic Elements provides a convenient bundling plugin that combines four essential text editing elements into a single package for the Plate rich-text editor framework. It bundles blockquote, code block, heading, and paragraph plugins with their default configurations, offering a simple way to add basic text editing capabilities to any Plate editor.

Package Information

• Package Name: @udecode/plate-basic-elements
• Package Type: npm
• Language: TypeScript
• Installation: npm install @udecode/plate-basic-elements

Core Imports

import { BaseBasicElementsPlugin } from '@udecode/plate-basic-elements';

For React-enhanced functionality:

import { BasicElementsPlugin } from '@udecode/plate-basic-elements/react';

Basic Usage

import { createPlateEditor } from '@udecode/plate/react';
import { BasicElementsPlugin } from '@udecode/plate-basic-elements/react';

// Create editor with basic elements
const editor = createPlateEditor({
  plugins: [
    BasicElementsPlugin,
    // ... other plugins
  ],
});

// The plugin automatically provides:
// - Blockquotes (Cmd+Shift+.)
// - Code blocks (Cmd+Alt+8) 
// - Headings H1-H3 (Cmd+Alt+1/2/3, Cmd+Shift+1/2/3)
// - Paragraphs (Cmd+Alt+0, Cmd+Shift+0)

For headless/server-side usage:

import { createSlateEditor } from '@udecode/plate';
import { BaseBasicElementsPlugin } from '@udecode/plate-basic-elements';

const editor = createSlateEditor({
  plugins: [
    BaseBasicElementsPlugin,
    // ... other plugins
  ],
});

Architecture

The package provides two plugin variants that bundle existing Plate plugins:

• BaseBasicElementsPlugin: Headless Slate.js integration without React dependencies
• BasicElementsPlugin: Full React integration with keyboard shortcuts and UI components

Both plugins are convenience wrappers that include four pre-configured plugins from separate packages.

Capabilities

Headless Basic Elements Plugin

The core plugin that bundles all basic elements functionality without React dependencies.

const BaseBasicElementsPlugin: SlatePlugin;

Plugin Configuration:

• Plugin Key: 'basicElements'
• Sub-plugins: Includes BaseBlockquotePlugin, BaseCodeBlockPlugin, BaseHeadingPlugin, BaseParagraphPlugin

React Basic Elements Plugin

React-enhanced plugin with keyboard shortcuts and UI components.

const BasicElementsPlugin: PlatePlugin;

Plugin Configuration:

• Plugin Key: 'basicElements'
• Sub-plugins: Includes BlockquotePlugin, CodeBlockPlugin, HeadingPlugin, ParagraphPlugin
• Keyboard Shortcuts: Inherits all shortcuts from constituent plugins

Bundled Plugin Details

This package bundles the following plugins from separate packages:

Blockquote Plugin

• Package: @udecode/plate-block-quote
• Plugin Key: 'blockquote'
• React Shortcut: Cmd+Shift+.
• Functionality: Blockquote elements for quotations and emphasis

Code Block Plugin

• Package: @udecode/plate-code-block
• Plugin Key: 'code_block'
• React Shortcut: Cmd+Alt+8
• Functionality: Multi-line code blocks with optional syntax highlighting

Heading Plugin

• Package: @udecode/plate-heading
• Plugin Key: 'heading'
• React Shortcuts: Cmd+Alt+1/2/3, Cmd+Shift+1/2/3 (H1-H3 only)
• Functionality: Heading elements (H1-H6)

Paragraph Plugin

• Package: @udecode/plate (core package)
• Plugin Key: 'p'
• React Shortcuts: Cmd+Alt+0, Cmd+Shift+0
• Functionality: Standard paragraph elements for text content

Accessing Individual Plugin APIs

The basic-elements package only exports the two bundled plugins. To access individual plugin APIs, transforms, types, or configurations, import directly from the source packages:

// For blockquote functionality
import { toggleBlockquote, withBlockquote } from '@udecode/plate-block-quote';

// For code block functionality  
import { 
  insertCodeBlock, 
  toggleCodeBlock,
  type TCodeBlockElement,
  type CodeBlockConfig 
} from '@udecode/plate-code-block';

// For heading functionality
import { 
  isHeading,
  HEADING_KEYS,
  type HeadingConfig
} from '@udecode/plate-heading';

Custom Configuration

To customize individual plugins while using the bundled approach, configure them separately:

import { createPlateEditor } from '@udecode/plate/react';
import { BlockquotePlugin } from '@udecode/plate-block-quote/react';
import { CodeBlockPlugin } from '@udecode/plate-code-block/react';
import { HeadingPlugin } from '@udecode/plate-heading/react';
import { ParagraphPlugin } from '@udecode/plate/react';

// Custom configuration approach
const editor = createPlateEditor({
  plugins: [
    BlockquotePlugin,
    CodeBlockPlugin.configure({ 
      options: { 
        defaultLanguage: 'typescript' 
      } 
    }),
    HeadingPlugin.configure({
      options: {
        levels: [1, 2, 3] // Only H1-H3
      }
    }),
    ParagraphPlugin,
  ],
});

Use Cases

Quick Setup

Use BasicElementsPlugin when you want standard basic elements with default settings:

import { BasicElementsPlugin } from '@udecode/plate-basic-elements/react';

const plugins = [BasicElementsPlugin];

Custom Configuration

Use individual plugins when you need custom configuration:

import { 
  BlockquotePlugin,
  CodeBlockPlugin, 
  HeadingPlugin,
  ParagraphPlugin
} from their respective packages;

const plugins = [
  BlockquotePlugin,
  CodeBlockPlugin.configure({ /* custom options */ }),
  HeadingPlugin.configure({ /* custom options */ }),
  ParagraphPlugin,
];

Headless Usage

Use BaseBasicElementsPlugin for server-side rendering or custom UI:

import { BaseBasicElementsPlugin } from '@udecode/plate-basic-elements';

const editor = createSlateEditor({
  plugins: [BaseBasicElementsPlugin]
});

Dependencies

This package has peer dependencies on:

• @udecode/plate (>=48.0.0)
• react (>=18.0.0) - for React plugin only
• react-dom (>=18.0.0) - for React plugin only

And direct dependencies on the bundled plugin packages:

• @udecode/plate-block-quote (48.0.0)
• @udecode/plate-code-block (48.0.0)
• @udecode/plate-heading (48.0.0)