Code Block

A composable code block with syntax highlighting, language selection, code formatting, and Mermaid diagram support.

// Generics with 'extends' and default values
function identity<T extends number | string = string>(arg: T): T {
  return arg;
}

let str = identity();  // Default type is string
let num = identity(42);  // T inferred as number

// Generic interfaces with 'extends' and default types
interface Box<T extends object = { message: string }> {
  content: T;
}

let defaultBox: Box = { content: { message: "Hello" } };
let customBox: Box<{ status: number }> = { content: { status: 200 } };

Supported Features

Controlled/Uncontrolled state management
Syntax highlighting via Shiki (50+ languages, 50+ themes)
Language selection with searchable menu
Code formatting via Prettier (JavaScript, TypeScript, JSON, HTML, CSS, SCSS, Less, Markdown, YAML, GraphQL)
Code wrapping toggle
Copy to clipboard
Caption support
Mermaid diagram preview
Readonly mode

Installation

pnpm add @notion-kit/code-block

pnpm add @notion-kit/code-block

Anatomy

<CodeBlock>
  <CodeBlockLang />
  <CodeBlockToolbar />
  <CodeBlockContent />
  <CodeBlockCaption />
</CodeBlock>

Examples

Uncontrolled

In uncontrolled mode, the component manages its own state internally. Use defaultValue to set the initial code and language.

// Generics with 'extends' and default values
function identity<T extends number | string = string>(arg: T): T {
  return arg;
}

let str = identity();  // Default type is string
let num = identity(42);  // T inferred as number

// Generic interfaces with 'extends' and default types
interface Box<T extends object = { message: string }> {
  content: T;
}

let defaultBox: Box = { content: { message: "Hello" } };
let customBox: Box<{ status: number }> = { content: { status: 200 } };

<CodeBlock
  defaultValue={{
    code: sampleCode,
    lang: "typescript",
  }}
>
  <CodeBlockLang />
  <CodeBlockToolbar />
  <CodeBlockContent />
  <CodeBlockCaption />
</CodeBlock>

<CodeBlock  defaultValue={{    code: sampleCode,    lang: "typescript",  }}>  <CodeBlockLang />  <CodeBlockToolbar />  <CodeBlockContent />  <CodeBlockCaption /></CodeBlock>

Controlled

In controlled mode, use value and onChange to manage state externally.

function greet(name: string): string {
  return `Hello, ${name}!`;
}

const result = greet("World");
console.log(result);

<CodeBlock value={value} onChange={setValue}>
  <CodeBlockLang />
  <CodeBlockToolbar />
  <CodeBlockContent />
  <CodeBlockCaption />
</CodeBlock>

<CodeBlock value={value} onChange={setValue}>  <CodeBlockLang />  <CodeBlockToolbar />  <CodeBlockContent />  <CodeBlockCaption /></CodeBlock>

Readonly

Use the readonly prop to prevent editing code, changing language, and editing the caption.

TypeScript

<CodeBlock
  readonly
  defaultValue={{
    code: sampleCode,
    lang: "typescript",
    caption: "This code block is readonly",
  }}
>
  <CodeBlockLang />
  <CodeBlockToolbar />
  <CodeBlockContent />
  <CodeBlockCaption />
</CodeBlock>

<CodeBlock  readonly  defaultValue={{    code: sampleCode,    lang: "typescript",    caption: "This code block is readonly",  }}>  <CodeBlockLang />  <CodeBlockToolbar />  <CodeBlockContent />  <CodeBlockCaption /></CodeBlock>

Mermaid Diagrams

When language is set to mermaid, a live diagram preview is rendered alongside the code editor.

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Success! 🎉]

Rendering diagram...

<CodeBlock
  defaultValue={{ code: mermaidCode, lang: "mermaid" }}
>
  <CodeBlockLang />
  <CodeBlockToolbar />
  <CodeBlockContent />
  <CodeBlockCaption />
</CodeBlock>

<CodeBlock  defaultValue={{ code: mermaidCode, lang: "mermaid" }}>  <CodeBlockLang />  <CodeBlockToolbar />  <CodeBlockContent />  <CodeBlockCaption /></CodeBlock>

API Reference

CodeBlock

The root component. Accepts all standard <div> props in addition to the following:

Prop	Type	Default	Description
`value`	`CodeBlockValue`	-	Controlled value. When provided, the component becomes controlled.
`defaultValue`	`Partial<CodeBlockValue>`	-	Default value for uncontrolled mode.
`onChange`	`(value: CodeBlockValue) => void`	-	Callback when value changes (controlled mode).
`readonly`	`boolean`	-	When `true`, prevents editing code, language, and caption.
`lastEditedBy`	`string`	-	Display name shown in the action menu footer.

CodeBlockContent

Renders the syntax-highlighted code with an editable textarea overlay. No additional props beyond standard <div> props.

CodeBlockLang

Renders the language selector button with a searchable dropdown menu.

CodeBlockToolbar

Renders the toolbar with copy-to-clipboard and action menu.

CodeBlockCaption

Renders an editable caption area below the code block. Disabled in readonly mode.

MermaidPreview

Renders a live Mermaid diagram preview. Only renders when the language is mermaid.

`type` CodeBlockValue

Prop	Type	Default	Description
`code`*	`string`	`""`	The source code content.
`lang`*	`string`	`"text"`	Programming language for highlighting.
`theme`	`string`	`"github-dark"`	Color theme for syntax highlighting.
`caption`	`string`	-	Optional caption text (HTML supported).
`wrap`	`boolean`	`false`	Whether to wrap code lines.
`ts`	`number`	`Date.now()`	Last edited timestamp in milliseconds.

Code Block

On this page