Skip to main content

Autoformat

Allows you to apply formatting based on character sequences, such as automatically converting # into an H1. This package also provides predefined rules.

Installation#

npm install @udecode/plate
# or
npm install @udecode/plate-autoformat

Usage#

import React from 'react';
import {
  AutoformatPlugin,
  createAutoformatPlugin,
  createExitBreakPlugin,
  createHorizontalRulePlugin,
  createListPlugin,
  createResetNodePlugin,
  createSoftBreakPlugin,
  Plate,
} from '@udecode/plate';
import { autoformatPlugin } from './autoformat/autoformatPlugin';
import { autoformatValue } from './autoformat/autoformatValue';
import { basicNodesPlugins } from './basic-nodes/basicNodesPlugins';
import { editableProps } from './common/editableProps';
import { plateUI } from './common/plateUI';
import { exitBreakPlugin } from './exit-break/exitBreakPlugin';
import { resetBlockTypePlugin } from './reset-node/resetBlockTypePlugin';
import { softBreakPlugin } from './soft-break/softBreakPlugin';
import { createMyPlugins, MyEditor, MyValue } from './typescript/plateTypes';

const plugins = createMyPlugins(
  [
    ...basicNodesPlugins,
    createListPlugin(),
    createHorizontalRulePlugin(),
    createResetNodePlugin(resetBlockTypePlugin),
    createSoftBreakPlugin(softBreakPlugin),
    createExitBreakPlugin(exitBreakPlugin),
    createAutoformatPlugin<AutoformatPlugin<MyValue, MyEditor>, MyValue>(
      autoformatPlugin
    ),
  ],
  {
    components: plateUI,
  }
);

export default () => (
  <Plate<MyValue>
    editableProps={editableProps}
    initialValue={autoformatValue}
    plugins={plugins}
  />
);

Rules#

This package provides the following rules:

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
autoformatSubscriptSymbols rules
autoformatSubscriptSymbols rules
autoformatSuperscriptNumbers rules
autoformatSuperscriptSymbols rules

Options#

export interface MatchRange {
start: string;
end: string;
}
export interface AutoformatQueryOptions
extends Omit<AutoformatCommonRule, 'query'> {
/**
* `insertText` text.
*/
text: string;
}
export interface AutoformatCommonRule {
/**
* 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.
*/
match: string | string[] | MatchRange | MatchRange[];
/**
* Triggering character to autoformat.
* @default the last character of `match` or `match.end`
*/
trigger?: string | string[];
/**
* If true, insert the triggering character after autoformatting.
* @default: false
*/
insertTrigger?: boolean;
/**
* Query to allow autoformat.
*/
query?: (editor: TEditor<V>, options: AutoformatQueryOptions) => boolean;
}
export interface AutoformatBlockRule extends AutoformatCommonRule {
/**
* - text: insert text.
* - block: set block type or custom format.
* - mark: insert mark(s) between matches.
* @default 'text'
*/
mode: 'block';
match: string | string[];
/**
* For `mode: 'block'`: set block type. If `format` is defined, this field is ignored.
* For `mode: 'mark'`: Mark(s) to add.
*/
type?: string;
/**
* If true, the trigger should be at block start to allow autoformatting.
* @default true
*/
triggerAtBlockStart?: boolean;
/**
* If true, allow to autoformat even if there is a block of the same type above the selected block.
* @default false
*/
allowSameTypeAbove?: boolean;
/**
* Function called just before `format`.
* Generally used to reset the selected block.
*/
preFormat?: (editor: TEditor<V>) => void;
/**
* Custom formatting function.
* @default setNodes(editor, { type }, { match: (n) => isBlock(editor, n) })
*/
format?: (editor: TEditor<V>) => void;
}
export interface AutoformatMarkRule extends AutoformatCommonRule {
mode: 'mark';
/**
* Mark(s) to add.
*/
type: string | string[];
/**
* If false, do not format when the string can be trimmed.
*/
ignoreTrim?: boolean;
}
export interface AutoformatTextRule extends AutoformatCommonRule {
mode: 'text';
match: string | string[];
/**
* string: the matched text is replaced by that string.
* string[]: the matched texts are replaced by these strings.
* function: called when there is a match.
*/
format:
| string
| string[]
| ((editor: TEditor<V>, options: GetMatchPointsReturnType) => void);
}
export type AutoformatRule =
| AutoformatBlockRule
| AutoformatMarkRule
| AutoformatTextRule;
export interface AutoformatPlugin {
/**
* A list of triggering rules.
*/
rules?: AutoformatRule[];
}

Source code#