Autoformat

PreviousNext

Automatic text formatting via shortcodes and markdown-like shortcuts.

Basic ElementsBasic MarksCode BlockList
Loading...

Features

  • Markdown-style shortcuts for blocks (e.g., # to H1, > for blockquote).
  • Inline mark formatting (e.g., **bold**, *italic*, ~~strikethrough~~).
  • Smart punctuation conversion (e.g., -- to —, ... to …).
  • Mathematical symbols and fractions.
  • Legal symbols and arrows.
  • Undo support on delete to reverse autoformatting.

Kit Usage

Installation

The fastest way to add autoformatting is with the AutoformatKit, which includes comprehensive formatting rules for blocks, marks, and text replacements.

Add Kit

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

Manual Usage

Installation

pnpm add @platejs/autoformat

Add Plugin

import { AutoformatPlugin } from '@platejs/autoformat';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    AutoformatPlugin,
  ],
});

Configure Plugin

Configure autoformat with custom rules:

import { AutoformatPlugin } from '@platejs/autoformat';
 
AutoformatPlugin.configure({
  options: {
    rules: [
      // Block rules
      {
        match: '# ',
        mode: 'block',
        type: 'h1',
      },
      {
        match: '> ',
        mode: 'block',
        type: 'blockquote',
      },
      // Mark rules
      {
        match: '**',
        mode: 'mark',
        type: 'bold',
      },
      {
        match: '*',
        mode: 'mark',
        type: 'italic',
      },
    ],
    enableUndoOnDelete: true,
  },
});

Advanced Configuration

Import predefined rule sets for comprehensive autoformatting:

import { AutoformatPlugin } from '@platejs/autoformat';
import {
  autoformatArrow,
  autoformatLegal,
  autoformatMath,
  autoformatPunctuation,
  autoformatSmartQuotes,
} from '@platejs/autoformat';
 
AutoformatPlugin.configure({
  options: {
    enableUndoOnDelete: true,
    rules: [
      // Custom block rules
      {
        match: '# ',
        mode: 'block',
        type: 'h1',
      },
      // Predefined rule sets
      ...autoformatSmartQuotes,
      ...autoformatPunctuation,
      ...autoformatArrow,
      ...autoformatLegal,
      ...autoformatMath,
    ].map((rule) => ({
      ...rule,
      // Disable autoformat in code blocks
      query: (editor) =>
        !editor.api.some({
          match: { type: 'code_block' },
        }),
    })),
  },
});
  • rules: Array of autoformat rules defining triggers and formatting actions.
  • enableUndoOnDelete: Allows undoing autoformat by pressing backspace.
  • query: Function to conditionally enable/disable rules based on context.

Using Regex Patterns

For more complex matching patterns, you can use regular expressions:

import { AutoformatPlugin } from '@platejs/autoformat';
import { toggleList } from '@platejs/list';
 
AutoformatPlugin.configure({
  options: {
    rules: [
      {
        match: [String.raw`^\d+\.$ `, String.raw`^\d+\)$ `],
        matchByRegex: true,
        mode: 'block',
        type: 'list',
        format: (editor, { matchString }) => {
          const number = Number(matchString.match(/\d+/)?.[0]) || 1;
          toggleList(editor, {
            listRestartPolite: number,
            listStyleType: 'ol',
          });
        },
      },
    ],
  },
});
  • matchByRegex: Enables regex pattern matching instead of string equality.
  • Note that Regex patterns only work with mode: 'block' and are applied at block start (triggerAtBlockStart: true).

Plugins

AutoformatPlugin

Plugin for automatic text formatting based on typing patterns.

Options

  • rules optional AutoformatRule[]

    A list of triggering rules. Can be one of: AutoformatBlockRule, AutoformatMarkRule, AutoformatTextRule. Each extends AutoformatCommonRule.

    • Default: []

  • enableUndoOnDelete optional boolean

    Enable undo on delete to reverse autoformatting.

    • Default: false

Predefined Rules

You can import the following predefined rule sets:

NameDescription
autoformatSmartQuotesConverts "text" to "text".
Converts 'text' to 'text'.
autoformatPunctuationConverts -- to —.
Converts ... to ….
Converts >> to ».
Converts << to «.
autoformatArrowConverts -> to →.
Converts <- to ←.
Converts => to ⇒.
Converts <= and ≤= to ⇐.
autoformatLegalConverts (tm) and (TM) to ™.
Converts (r) and (R) to ®.
Converts (c) and (C) to ©.
autoformatLegalHtmlConverts &trade; to ™.
Converts &reg; to ®.
Converts &copy; to ©.
Converts &sect; to §.
autoformatComparisonConverts !> to ≯.
Converts !< to ≮.
Converts >= to ≥.
Converts <= to ≤.
Converts !>= to ≱.
Converts !<= to ≰.
autoformatEqualityConverts != to ≠.
Converts == to ≡.
Converts !== and ≠= to ≢.
Converts ~= to ≈.
Converts !~= to ≉.
autoformatFractionConverts 1/2 to ½.
Converts 1/3 to ⅓.
...
Converts 7/8 to ⅞.
autoformatDivisionConverts // to ÷.
autoformatOperationConverts +- to ±.
Converts %% to ‰.
Converts %%% and ‰% to ‱.
autoformatDivision rules.
autoformatSubscriptNumbersConverts ~0 to ₀.
Converts ~1 to ₁.
...
Converts ~9 to ₉.
autoformatSubscriptSymbolsConverts ~+ to ₊.
Converts ~- to ₋.
autoformatSuperscriptNumbersConverts ^0 to ⁰.
Converts ^1 to ¹.
...
Converts ^9 to ⁹.
autoformatSuperscriptSymbolsConverts ^+ to ⁺.
Converts ^- to ⁻.
autoformatMathautoformatComparison rules
autoformatEquality rules
autoformatOperation rules
autoformatFraction rules
autoformatSubscriptNumbers rules
autoformatSubscriptSymbols rules
autoformatSuperscriptNumbers rules
autoformatSuperscriptSymbols rules

Types

AutoformatCommonRule

An interface for the common structure of autoformat rules, regardless of their mode.

Attributes

Collapse all

  • match string | string[] | MatchRange | MatchRange[]

    The rule applies when the trigger and the text just before the cursor matches.

    • For mode: 'block': lookup for the end match(es) before the cursor.
    • For mode: 'text': lookup for the end match(es) before the cursor. If format is an array, also lookup for the start match(es).
    • For mode: 'mark': lookup for the start and end matches.
    • Note: '_*', ['_*'] and { start: '_*', end: '*_' } are equivalent.
    • MatchRange:

  • trigger optional string | string[]

    Triggering character to autoformat.

  • insertTrigger optional boolean

    If true, insert the triggering character after autoformatting.

    • Default: false

  • query optional (editor: PlateEditor, options: AutoformatQueryOptions) => boolean

    A query function to allow autoformat.

    OptionsAutoformatQueryOptions

    Collapse all

    • text string

      insertText text.

AutoformatBlockRule

An interface for autoformat rules for block mode.

Attributes

Collapse all

  • mode 'block'

    Block mode: set block type or custom format.

  • match string | string[]

    Pattern to match for the autoformat rule.

  • type optional string

    For mode: 'block': set block type. If format is defined, this field is ignored.

  • triggerAtBlockStart optional boolean

    Whether trigger should be at block start.

    • Default: true

  • allowSameTypeAbove optional boolean

    Whether to allow autoformat with same block type above.

    • Default: false

  • preFormat optional (editor: PlateEditor) => void

    Function called before format. Used to reset selected block.

  • format optional (editor: PlateEditor) => void

    Custom formatting function.

AutoformatMarkRule

An interface for autoformat rules for mark mode.

Attributes

Collapse all

  • mode 'mark'

    Mark mode: insert mark(s) between matches.

  • type string | string[]

    Mark(s) to add.

  • ignoreTrim optional boolean

    Whether to format when string can be trimmed.

AutoformatTextRule

An interface for autoformat rules for text mode.

Parameters

Collapse all

  • mode 'text'

    Text mode: insert text.

  • match string | string[]

    Pattern to match for the autoformat rule.

  • format string | string[] | ((editor: PlateEditor, options: GetMatchPointsReturnType) => void)

    Text replacement or formatting function.

自动格式化块菜单