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-autoformat

Usage#

Live Editor
Result

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, 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) => void;
/**
* Custom formatting function.
* @default setNodes(editor, { type }, { match: (n) => Editor.isBlock(editor, n) })
*/
format?: (editor: TEditor) => 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, options: GetMatchPointsReturnType) => void);
}
export type AutoformatRule =
| AutoformatBlockRule
| AutoformatMarkRule
| AutoformatTextRule;
export interface AutoformatPlugin {
/**
* A list of triggering rules.
*/
rules?: AutoformatRule[];
}

Source code#