Code Block

PreviousNext

Display code with syntax highlighting.

PlusCode Block Element
Loading…

Features

  • Syntax highlighting for code blocks
  • Support for multiple programming languages
  • Customizable language selection
  • Proper indentation handling
  • Markdown code fence shortcuts through CodeBlockRules.markdown({ on })

Kit Usage

Installation

The fastest way to add code block functionality is with the CodeBlockKit, which includes pre-configured CodeBlockPlugin, CodeLinePlugin, and CodeSyntaxPlugin with syntax highlighting, the shipped triple-backtick input rule, and Plate UI components.

'use client';
 
import { CodeBlockRules } from '@platejs/code-block';
import {
  CodeBlockPlugin,
  CodeLinePlugin,
  CodeSyntaxPlugin,
} from '@platejs/code-block/react';
import { all, createLowlight } from 'lowlight';
 
import {
  CodeBlockElement,
  CodeLineElement,
  CodeSyntaxLeaf,
} from '@/components/ui/code-block-node';
 
const lowlight = createLowlight(all);
 
export const CodeBlockKit = [
  CodeBlockPlugin.configure({
    inputRules: [CodeBlockRules.markdown({ on: 'match' })],
    node: { component: CodeBlockElement },
    options: { lowlight },
    shortcuts: { toggle: { keys: 'mod+alt+8' } },
  }),
  CodeLinePlugin.withComponent(CodeLineElement),
  CodeSyntaxPlugin.withComponent(CodeSyntaxLeaf),
];
'use client';
 
import { CodeBlockRules } from '@platejs/code-block';
import {
  CodeBlockPlugin,
  CodeLinePlugin,
  CodeSyntaxPlugin,
} from '@platejs/code-block/react';
import { all, createLowlight } from 'lowlight';
 
import {
  CodeBlockElement,
  CodeLineElement,
  CodeSyntaxLeaf,
} from '@/components/ui/code-block-node';
 
const lowlight = createLowlight(all);
 
export const CodeBlockKit = [
  CodeBlockPlugin.configure({
    inputRules: [CodeBlockRules.markdown({ on: 'match' })],
    node: { component: CodeBlockElement },
    options: { lowlight },
    shortcuts: { toggle: { keys: 'mod+alt+8' } },
  }),
  CodeLinePlugin.withComponent(CodeLineElement),
  CodeSyntaxPlugin.withComponent(CodeSyntaxLeaf),
];

Add Kit

Add the kit to your plugins:

import { createPlateEditor } from 'platejs/react';
import { CodeBlockKit } from '@/components/editor/plugins/code-block-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...CodeBlockKit,
  ],
});
import { createPlateEditor } from 'platejs/react';
import { CodeBlockKit } from '@/components/editor/plugins/code-block-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...CodeBlockKit,
  ],
});

Manual Usage

Installation

pnpm add @platejs/code-block lowlight
pnpm add @platejs/code-block lowlight

Add Plugins

Include the code block plugins in your Plate plugins array when creating the editor.

import { CodeBlockPlugin, CodeLinePlugin, CodeSyntaxPlugin } from '@platejs/code-block/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeBlockPlugin,
    CodeLinePlugin,
    CodeSyntaxPlugin,
  ],
});
import { CodeBlockPlugin, CodeLinePlugin, CodeSyntaxPlugin } from '@platejs/code-block/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeBlockPlugin,
    CodeLinePlugin,
    CodeSyntaxPlugin,
  ],
});

Configure Plugins

Configure the plugins with syntax highlighting and custom components.

Basic Setup with All Languages:

import { CodeBlockRules } from '@platejs/code-block';
import { CodeBlockPlugin, CodeLinePlugin, CodeSyntaxPlugin } from '@platejs/code-block/react';
import { all, createLowlight } from 'lowlight';
import { createPlateEditor } from 'platejs/react';
import { CodeBlockElement, CodeLineElement, CodeSyntaxLeaf } from '@/components/ui/code-block-node';
 
// Create a lowlight instance with all languages
const lowlight = createLowlight(all);
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeBlockPlugin.configure({
      inputRules: [CodeBlockRules.markdown({ on: 'match' })],
      node: { component: CodeBlockElement },
      options: { lowlight },
      shortcuts: { toggle: { keys: 'mod+alt+8' } },
    }),
    CodeLinePlugin.withComponent(CodeLineElement),
    CodeSyntaxPlugin.withComponent(CodeSyntaxLeaf),
  ],
});
import { CodeBlockRules } from '@platejs/code-block';
import { CodeBlockPlugin, CodeLinePlugin, CodeSyntaxPlugin } from '@platejs/code-block/react';
import { all, createLowlight } from 'lowlight';
import { createPlateEditor } from 'platejs/react';
import { CodeBlockElement, CodeLineElement, CodeSyntaxLeaf } from '@/components/ui/code-block-node';
 
// Create a lowlight instance with all languages
const lowlight = createLowlight(all);
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeBlockPlugin.configure({
      inputRules: [CodeBlockRules.markdown({ on: 'match' })],
      node: { component: CodeBlockElement },
      options: { lowlight },
      shortcuts: { toggle: { keys: 'mod+alt+8' } },
    }),
    CodeLinePlugin.withComponent(CodeLineElement),
    CodeSyntaxPlugin.withComponent(CodeSyntaxLeaf),
  ],
});

Custom Language Setup (Optimized Bundle):

For optimized bundle size, you can register only specific languages:

import { createLowlight } from 'lowlight';
import css from 'highlight.js/lib/languages/css';
import js from 'highlight.js/lib/languages/javascript';
import ts from 'highlight.js/lib/languages/typescript';
import html from 'highlight.js/lib/languages/xml';
 
// Create a lowlight instance
const lowlight = createLowlight();
 
// Register only the languages you need
lowlight.register('html', html);
lowlight.register('css', css);
lowlight.register('js', js);
lowlight.register('ts', ts);
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeBlockPlugin.configure({
      inputRules: [CodeBlockRules.markdown({ on: 'match' })],
      node: { component: CodeBlockElement },
      options: {
        lowlight,
        defaultLanguage: 'js', // Set default language (optional)
      },
      shortcuts: { toggle: { keys: 'mod+alt+8' } },
    }),
    CodeLinePlugin.withComponent(CodeLineElement),
    CodeSyntaxPlugin.withComponent(CodeSyntaxLeaf),
  ],
});
import { createLowlight } from 'lowlight';
import css from 'highlight.js/lib/languages/css';
import js from 'highlight.js/lib/languages/javascript';
import ts from 'highlight.js/lib/languages/typescript';
import html from 'highlight.js/lib/languages/xml';
 
// Create a lowlight instance
const lowlight = createLowlight();
 
// Register only the languages you need
lowlight.register('html', html);
lowlight.register('css', css);
lowlight.register('js', js);
lowlight.register('ts', ts);
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeBlockPlugin.configure({
      inputRules: [CodeBlockRules.markdown({ on: 'match' })],
      node: { component: CodeBlockElement },
      options: {
        lowlight,
        defaultLanguage: 'js', // Set default language (optional)
      },
      shortcuts: { toggle: { keys: 'mod+alt+8' } },
    }),
    CodeLinePlugin.withComponent(CodeLineElement),
    CodeSyntaxPlugin.withComponent(CodeSyntaxLeaf),
  ],
});
  • node.component: Assigns CodeBlockElement to render code block containers.
  • inputRules: Registers the triple-backtick fence rule. Use on: 'match' to commit when the fence becomes complete or on: 'break' to commit on Enter.
  • options.lowlight: Lowlight instance for syntax highlighting.
  • options.defaultLanguage: Default language when no language is specified.
  • shortcuts.toggle: Defines a keyboard shortcut to toggle code blocks.
  • withComponent: Assigns components for code lines and syntax highlighting.

For the runtime model, see Plugin Input Rules.

Turn Into Toolbar Button

You can add this item to the Turn Into Toolbar Button to convert blocks into code blocks:

{
  icon: <FileCodeIcon />,
  label: 'Code',
  value: KEYS.codeBlock,
}
{
  icon: <FileCodeIcon />,
  label: 'Code',
  value: KEYS.codeBlock,
}

Insert Toolbar Button

You can add this item to the Insert Toolbar Button to insert code block elements:

{
  icon: <FileCodeIcon />,
  label: 'Code',
  value: KEYS.codeBlock,
}
{
  icon: <FileCodeIcon />,
  label: 'Code',
  value: KEYS.codeBlock,
}

Plugins

CodeBlockPlugin

Options

    Default language to use when no language is specified. Set to null to disable syntax highlighting by default.

    Lowlight instance to use for highlighting. If not provided, syntax highlighting will be disabled.

Commands

Install CodeBlockPlugin, then mutate code blocks through its command group.

editor.update.code_block.insert();
editor.update.code_block.toggle();
editor.update.code_block.tab();
editor.update.code_block.untab();
editor.update.code_block.resetBlock();
editor.update.code_block.selectAll();
editor.update.code_block.insert();
editor.update.code_block.toggle();
editor.update.code_block.tab();
editor.update.code_block.untab();
editor.update.code_block.resetBlock();
editor.update.code_block.selectAll();
  • insert() converts an empty selected block in place. For non-empty or expanded selections, it inserts and selects a paragraph after the range-end block, then converts that paragraph. It is a no-op without a selection.
  • toggle() converts selected blocks to or from code blocks.
  • tab() and untab() indent or outdent selected code lines by two spaces.
  • resetBlock() unwraps the selected code block into paragraphs.
  • selectAll() selects the containing code block.

Queries

isCodeBlockEmpty

Returnsboolean

    Whether the selection is in an empty code block.

isSelectionAtCodeBlockStart

Returnsboolean

    Whether the selection is at the start of the first code line in a code block.