Create custom rich text plugins

In this how-to, you'll learn how to create custom rich text plugins in React Bricks.

This is an advanced topic. For most projects, the normal RichText component is still the best choice.

If you only need to restyle built-in rich text features like bold text or links, use the normal RichText render functions. Use custom plugins only when you want to add a new toolbar button or deeply customize the behavior of an existing one.

Docs reference: RichTextExt

When to use RichTextExt

Use RichTextExt when you want to:

• add a brand-new formatting button
• replace the icon, label, shortcut, or render logic of an existing feature
• add a custom block type
• create a plugin that needs a popup or modal to collect extra data

The official docs explicitly note that for most use cases, the normal RichText is simpler.

Related reading: Customize rich text styles

RichTextExt uses plugins, not allowedFeatures

With the standard RichText, you configure things like allowedFeatures, renderBold, and renderLink.

With RichTextExt, those are replaced by a plugins array.

For example:

<RichTextExt
  propName="text"
  value={text}
  plugins={[bold, italic, link]}
/>

Each plugin controls:

• the toolbar button
• the hotkey
• the render function
• the toggle behavior

Start from the built-in plugins

Usually you do not start from zero.

React Bricks exposes predefined plugins, and you can:

• use them as they are
• override parts of them, such as the icon, hotkey, label, or render function
• add your own next to them

For example, you can start from the built-in plugins and override just one of them:

import { RichTextExt as RichText, plugins } from 'react-bricks/rsc'
 
const { bold, italic, unorderedList, link, quote } = plugins
 
const MyRichText = ({ text }) => {
  return (
    <RichText
      propName="text"
      value={text}
      placeholder="Type some text..."
      plugins={[
        bold,
        italic,
        unorderedList,
        link,
        {
          ...quote,
          renderElement: ({ children }) => (
            <div className="border-l-4 border-pink-500 pl-4 text-xl text-pink-500">
              {children}
            </div>
          ),
          hotKey: 'mod+opt+q',
        },
      ]}
    />
  )
}

This is often the best starting point when your needs are close to the default behavior. You keep the built-in plugin logic, but customize the part that matters to your project.

A simple custom plugin with markPluginConstructor

For a mark-style plugin, such as highlight, badge, or inline emphasis, use markPluginConstructor.

Here is a simple example that adds a custom "badge" style:

import { FaTag } from 'react-icons/fa'
import {
  RichTextExt as RichText,
  markPluginConstructor,
  plugins,
} from 'react-bricks/rsc'
 
const { bold, italic, link } = plugins
 
const badge = markPluginConstructor({
  name: 'badge',
  label: 'Badge',
  hotKey: 'mod+shift+b',
  render: ({ children }) => (
    <span className="rounded bg-sky-100 px-2 py-1 text-sky-800">
      {children}
    </span>
  ),
  icon: <FaTag />,
})
 
const MyRichText = ({ text }) => {
  return (
    <RichText
      propName="text"
      value={text}
      placeholder="Type some text..."
      plugins={[bold, italic, link, badge]}
    />
  )
}

This creates a new toolbar button that applies your custom inline style.

Docs reference: markPluginConstructor

Use blockPluginConstructor for custom blocks

If your plugin represents a block or list element, use blockPluginConstructor.

This is the right choice for things like:

• a custom callout block
• a branded quote block
• a heading variant
• a list style with custom item rendering

Conceptually:

• use markPluginConstructor for inline styles
• use blockPluginConstructor for blocks and lists

Docs reference: blockPluginConstructor

Use blockWithModalPluginConstructor for popup-driven plugins

Some plugins need more than just a toggle.

For example, a plugin may need editors to choose:

• a stock code
• a product ID
• a variant
• a visual style

That is where blockWithModalPluginConstructor is useful.

It lets you define:

• pluginCustomFields
• getDefaultProps
• renderAdmin
• renderItemAdmin

So the plugin can open a configuration UI, save structured values, and render based on those values.

This is the most powerful option, and also the most advanced one.

Docs reference: blockWithModalPluginConstructor

A practical way to choose

Use:

• RichText if you only need standard rich text and custom render functions
• RichTextExt with markPluginConstructor for a new inline style button
• RichTextExt with blockPluginConstructor for a new block or list button
• RichTextExt with blockWithModalPluginConstructor when the plugin needs extra structured data from editors

Related reading

• Customize rich text styles
• RichTextExt

Summary

Custom rich text plugins are the advanced extension point for RichTextExt.

Use them when you want more than styling. They let you create new buttons, new behaviors, and even popup-configured rich text features tailored to your product.