CodeBlock

Create code blocks with syntax highlighting support and language detection.

The CodeBlock extension allows you to create code blocks for displaying code snippets. It supports language specification, syntax highlighting, and special keyboard handling for code editing.

Installation

npm

npm install @tiptap/extension-code-block

Usage

The CodeBlock extension is included in the StarterKit by default:

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'

const editor = new Editor({
  extensions: [StarterKit],
})

To use it standalone:

import { Editor } from '@tiptap/core'
import Document from '@tiptap/extension-document'
import CodeBlock from '@tiptap/extension-code-block'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'

const editor = new Editor({
  extensions: [
    Document,
    Paragraph,
    Text,
    CodeBlock,
  ],
})

Configuration

languageClassPrefix

Prefix for language classes applied to code tags.

languageClassPrefix · string | null · default: "'language-'"

Adds a prefix to language classes that are applied to code tags.

CodeBlock.configure({
  languageClassPrefix: 'language-',
})

exitOnTripleEnter

Defines whether the node should be exited on triple enter.

exitOnTripleEnter · boolean · default: "true"

Exit the code block when pressing Enter three times.

CodeBlock.configure({
  exitOnTripleEnter: true,
})

exitOnArrowDown

Defines whether the node should be exited on arrow down when at the end.

exitOnArrowDown · boolean · default: "true"

Exit the code block when pressing arrow down at the end if there is no node after it.

CodeBlock.configure({
  exitOnArrowDown: true,
})

defaultLanguage

The default language for code blocks.

defaultLanguage · string | null · default: "null"

Set a default language for all code blocks.

CodeBlock.configure({
  defaultLanguage: 'javascript',
})

enableTabIndentation

Enables tab key for indentation in code blocks.

enableTabIndentation · boolean · default: "false"

When enabled, pressing Tab will insert spaces for indentation instead of changing focus.

CodeBlock.configure({
  enableTabIndentation: true,
})

tabSize

The number of spaces to use for tab indentation.

tabSize · number · default: "4"

Number of spaces to insert when pressing Tab (only when enableTabIndentation is true).

CodeBlock.configure({
  enableTabIndentation: true,
  tabSize: 2,
})

HTMLAttributes

Custom HTML attributes to add to the rendered code block element.

HTMLAttributes · Record<string, any> · default: "{}"

Custom HTML attributes that should be added to the rendered HTML tag.

CodeBlock.configure({
  HTMLAttributes: {
    class: 'my-code-block',
  },
})

Commands

setCodeBlock

Converts the current node to a code block.

editor.commands.setCodeBlock()

// With language specification
editor.commands.setCodeBlock({ language: 'javascript' })

toggleCodeBlock

Toggles a code block. If the current node is already a code block, it converts it to a paragraph.

editor.commands.toggleCodeBlock()

// With language specification
editor.commands.toggleCodeBlock({ language: 'python' })

Keyboard Shortcuts

• Mod-Alt-C: Toggle code block
• Backspace: Remove code block when empty or at start
• Tab: Insert indentation (when enableTabIndentation is true)
• Shift-Tab: Remove indentation (when enableTabIndentation is true)
• Enter: Exit code block on triple enter (when exitOnTripleEnter is true)
• ArrowDown: Exit code block when at end (when exitOnArrowDown is true)

Input Rules

The CodeBlock extension supports Markdown-style input rules:

• Type ``` followed by a space to create a code block
• Type ``` followed by a language name and space to create a code block with that language
• Type ~~~ followed by a space as an alternative syntax

Features

VS Code Paste Support

The extension automatically detects code pasted from VS Code and creates a code block with the correct language.

Tab Indentation

When enableTabIndentation is enabled, you can use Tab and Shift-Tab to indent and unindent code:

• Tab on a selection: Indents all selected lines
• Shift-Tab on a selection: Unindents all selected lines
• Tab without selection: Inserts indentation at cursor
• Shift-Tab without selection: Removes indentation at cursor

Source Code

View the source code on GitHub:

packages/extension-code-block/src/code-block.ts