@portabletext/plugin-typography

@portabletext/plugin-typography

Automatically transform text to typographic variants

Drop-in plugin for the Portable Text Editor to enable a wide variety of typographic transformations:

Automatically handles smart undo with Backspace right after insertion:

Installation

npm install @portabletext/plugin-typography

Usage

Import the TypographyPlugin React component and place it inside the EditorProvider:

import {
  defineSchema,
  EditorProvider,
  PortableTextEditable,
} from '@portabletext/editor'
import {TypographyPlugin} from '@portabletext/plugin-typography'

const schemaDefinition = defineSchema({
  // Your Schema
})

function App() {
  return (
    <EditorProvider
      initialConfig={{
        schemaDefinition,
      }}
    >
      <PortableTextEditable />
      <TypographyPlugin /> {/* <-- plugin added */}
    </EditorProvider>
  )
}

Rules included

The plugin includes the following typographic transformation rules:

Default rules:

Name	Conversion
emDash	-- → —
ellipsis	... → …
openingDoubleQuote	" → “
closingDoubleQuote	" → ”
openingSingleQuote	' → ‘
closingSingleQuote	' → ’
leftArrow	<- → ←
rightArrow	-> → →
copyright	(c) → ©
trademark	(tm) → ™
servicemark	(sm) → ℠
registeredTrademark	(r) → ®

Optional rules:

Name	Conversion
oneHalf	1/2 → ½
plusMinus	+/- → ±
notEqual	!= → ≠
laquo	<< → «
raquo	>> → »
multiplication	* or x between numbers → ×
superscriptTwo	^2 → ²
superscriptThree	^3 → ³
oneQuarter	1/4 → ¼
threeQuarters	3/4 → ¾

Configuring rules

The plugin supports flexible configuration through preset, enable, and disable props:

Using presets

The preset prop provides quick configuration:

• 'default' (default): Common typography rules enabled
• 'all': Enable all rules
• 'none': Start with no rules (use with enable)

// Use default rules (most common transformations)
<TypographyPlugin />

// Enable everything
<TypographyPlugin preset="all" />

// Start from scratch and enable only specific rules
<TypographyPlugin preset="none" enable={['emDash', 'ellipsis']} />

Enabling additional rules

Use enable to add rules beyond the preset:

// Add multiplication and plusMinus to default rules
<TypographyPlugin enable={['multiplication', 'plusMinus']} />

// Enable all rules except a few
<TypographyPlugin preset="all" disable={['emDash', 'ellipsis']} />

Disabling rules

Use disable to remove rules from the preset:

// Use defaults but disable quote transformations
<TypographyPlugin
  disable={[
    'openingDoubleQuote',
    'closingDoubleQuote',
    'openingSingleQuote',
    'closingSingleQuote',
  ]}
/>

Combining options

All three props work together. The order of operations is:

1. Start with preset (default: 'default')
2. Add rules from enable
3. Remove rules from disable

// Start with all rules, then customize
<TypographyPlugin
  preset="all"
  disable={['multiplication']}
/>

// Start with none, enable only math symbols
<TypographyPlugin
  preset="none"
  enable={['multiplication', 'plusMinus', 'notEqual']}
/>

Controlling when text transformations run

The TypographyPlugin has an optional guard prop that accepts any type of BehaviorGuard. Here, you'll have access to the current EditorSnapshot as well as information about the current rule being matched.

Because disallowing text transformations inside code is a common use case, this plugin ships a built-in createDecoratorGuard function. Use that to create a guard that only allows text transformations inside certain decorators:

import {
  createDecoratorGuard,
  TypographyPlugin,
} from '@portabletext/plugin-typography'

return (
  <TypographyPlugin
    guard={createDecoratorGuard({
      decorators: ({context}) =>
        context.schema.decorators.flatMap((decorator) =>
          decorator.name === 'code' ? [] : [decorator.name],
        ),
    })}
  />
)

The decorators callback derives its allowed list from context.schema rather than hardcoding decorator names, so the guard tracks whatever the schema actually declares instead of a fixed list that can drift from it. Because context.schema is resolved at the caret, it also follows containers: inside a code block the guard sees that container's sub-schema rather than the top-level one, which is what lets a guard keyed on the code decorator suppress transformations inside a code block whose sub-schema defines code.

Using individual rules with InputRulePlugin

All included typographic rules are exported from the plugin. To use them in your own abstraction, import them from this plugin and use them with the InputRulePlugin:

import {InputRulePlugin} from '@portabletext/plugin-input-rule'
import {ellipsisRule, emDashRule} from '@portabletext/plugin-typography'

return <InputRulePlugin rules={[emDashRule, ellipsisRule]} />