Code Blocks

Code blocks are a simple way to display formatted code with syntax highlighting.

Code blocks by default are a simple way to display code. But, BlockNote also supports more advanced features like:

• Syntax highlighting
• Custom themes
• Multiple languages
• Tab indentation

Configuration Options

type CodeBlockOptions = {
  indentLineWithTab?: boolean;
  defaultLanguage?: string;
  supportedLanguages?: Record<
    string,
    {
      name: string;
      aliases?: string[];
    }
  >;
};

indentLineWithTab: Whether the Tab key should indent lines, or not be handled by the code block specially. Defaults to true.

defaultLanguage: The syntax highlighting default language for code blocks which are created/inserted without a set language, which is text by default (no syntax highlighting).

supportedLanguages: The syntax highlighting languages supported by the code block, which is an empty array by default.

Syntax Highlighting

Syntax highlighting is handled by a separate editor extension, configured at the editor level via the syntaxHighlighting option (not on the code block itself), so it can highlight any block's content:

type SyntaxHighlightingOptions = {
  createHighlighter?: () => Promise<HighlighterGeneric<any, any>>;
  highlightBlock?: (block: {
    type: string;
    props: Record<string, any>;
  }) => string | undefined;
};

createHighlighter: The Shiki highlighter to use for syntax highlighting.

highlightBlock: Picks the language to highlight a block's content as (return the language key, or undefined to leave it un-highlighted). This is how you enable highlighting for specific blocks. Defaults to the block's language prop ((block) => block.props.language), which covers the code block. For a block with a fixed language, return it directly — e.g. for a math block: (block) => (block.type === "math" ? "latex" : block.props.language).

BlockNote provides a generic, ready-to-use set of these in the @blocknote/code-block package, which supports a wide range of languages. The code block options and the highlighter are exported separately:

import { createCodeBlockSpec } from "@blocknote/core";
import { codeBlockOptions, createHighlighter } from "@blocknote/code-block";

const editor = useCreateBlockNote({
  syntaxHighlighting: { createHighlighter },
  schema: BlockNoteSchema.create().extend({
    blockSpecs: {
      codeBlock: createCodeBlockSpec(codeBlockOptions),
    },
  }),
});

See this example to see it in action.

Type & Props

type CodeBlock = {
  id: string;
  type: "codeBlock";
  props: {
    language: string;
  };
  content: InlineContent[];
  children: Block[];
};

language: The syntax highlighting language to use. Defaults to text, which has no highlighting.

Custom Syntax Highlighting

To create your own syntax highlighter, you can use the shiki-codegen CLI for generating the code to create one for your chosen languages and themes.

For example, to create a syntax highlighter using the optimized javascript engine, javascript, typescript, vue, with light and dark themes, you can run the following command:

npx shiki-codegen --langs javascript,typescript,vue --themes light-plus,dark-plus --engine javascript --precompiled ./shiki.bundle.ts

This will generate a shiki.bundle.ts file that you can use to create a syntax highlighter for your editor.

Like this:

import { createHighlighter } from "./shiki.bundle.js";

export default function App() {
  const editor = useCreateBlockNote({
    // The highlighter is configured at the editor level, separately from the
    // code block's own options.
    syntaxHighlighting: {
      createHighlighter: () =>
        createHighlighter({
          themes: ["light-plus", "dark-plus"],
          langs: [],
        }),
    },
    schema: BlockNoteSchema.create().extend({
      blockSpecs: {
        codeBlock: createCodeBlockSpec({
          indentLineWithTab: true,
          defaultLanguage: "typescript",
          supportedLanguages: {
            typescript: {
              name: "TypeScript",
              aliases: ["ts"],
            },
          },
        }),
      },
    }),
  });

  return <BlockNoteView editor={editor} />;
}

See the custom code block example for a more detailed example.