RichTextExt (Extensible RichText)

The RichTextExt component is an extensible version of the RichText component.

Unlike the standard RichText, it employs a plugin system. This allows you to replace any part of a default plugin—not just the render function, but also the button icon, label, shortcut key, etc.—and add new plugins.

Note: for most use cases, you should use the normal RichText, which is simpler to use.

Usage Example

In this example, we’re not creating custom plugins. Instead, we’re configuring the RichTextExt component to use predefined rich text plugins while overriding the shortcut key and render function of the “quote” plugin:

import { RichTextExt as RichText, plugins } from 'react-bricks/frontend'

const { bold, italic, unorderedList, link, quote } = plugins

return (
  <RichText
    renderBlock={({ children }) => (
      <p className="text-lg sm:text-xl text-center">{props.children}</p>
    )}
    placeholder="Type a text..."
    propName="text"
    plugins={[
      bold,
      italic,
      unorderedList,
      link,
      {
        ...quote,
        renderElement: ({ children }) => (
          <div className="border-l-4 pl-4 border-pink-500 text-pink-500 text-xl">
            {children}
          </div>
        ),
        hotKey: 'mod+opt+q',
      },
    ]}
  />
)

Properties

Here’s the Typescript interface for the props of the RichTextExt component:

interface RichTextProps {
  propName?: string
  value?: types.TextValue
  renderBlock?: (props: { children: React.ReactElement }) => JSX.Element
  placeholder?: string
  renderPlaceholder?: (props: { children: React.ReactElement }) => JSX.Element
  multiline?: boolean
  softLineBreak?: boolean
  metaFieldName?: 'title' | 'description' | 'language'
  customFieldName?: string
  customFieldPlainText?: boolean
  plugins?: types.RichTextPlugin[]
}

Properties Definition

For props shared with the RichText component, refer to the RichText documentation. Note that for RichTextExt, properties like allowedFeatures and all render functions (e.g., renderBold) are replaced by the plugins property.

Property	Definition
`plugins`	An array of plugins extending the rich text functionality, each of type `RichTextPlugin`

RichTextPlugin is defined as follows:

interface RichTextPlugin {
  type: 'Mark' | 'Block' | 'List'
  name: string
  isInline?: boolean
  itemName?: string
  label: string
  hotKey?: string
  renderElement?: (props: RenderElementProps) => JSX.Element
  renderItemElement?: (props: RenderElementProps) => JSX.Element
  renderLeaf?: (props: RenderLeafProps) => JSX.Element
  toggle: (editor: Editor, plugins: RichTextPlugin[]) => void
  button?: {
    icon: React.ReactElement
    isActive: (editor: Editor) => boolean
  }
  enhanceEditor?: (editor: Editor) => Editor
}

React Bricks uses Slate as its underlying rich text editor.
The RenderElementProps and RenderLeafProps are types from Slate.

RichTextPlugin properties

Plugin	Definition
`type`	A plugin can be of type “Mark” (a style like bold), “Block” (e.g., an heading) or “List” (for a list of items, like UL).
`name`	Name of the plugin.
`isInline?`	Indicates if the element is inline (e.g., for links).
`itemName?`	Name of the items element in case of a list
`label`	Displayed when hovering over the button
`hotKey?`	Shortcut key to apply this marker or block type
`renderElement?`	Render function for a block plugin. Key arguments: `children` (actual text content), `attributes` (to be spread on the top-level DOM element) and `element` (an object whose `type` is the plugin name).
`renderItemElement?`	Render function for a single list item (e.g., a `li` element).
`renderLeaf?`	Render function for a mark plugin (e.g., bold or italic). Arguments: `children`, `attributes` and `leaf`. Leaf is an object with truthy keys for applied markers (e.g. `if (leaf.bold) {...}`).
`toggle`	Function to toggle the marker or block on the editor.
`button`	Customizes the default button for a plugin or configures the button for a new plugin, providing the `icon` (a `ReactElement`) and a `isActive` function.
`enhanceEditor`	Function to enhance the Slate editor. Returns an enhanced editor. Refer to Slate documentation. This is a very powerful option to customize the React Bricks RichText behavior.

Plugins helpers

For common marker (bold, italic, highlight…) or block (heading, quote, etc.) plugins, React Bricks provides helpers that allow you to create new plugins very quickly:

There’s also a helper for creating complex plugins that require a popup configuration interface. This helper enables you to add custom fields of various types (such as text, select, and autocomplete) that content editors can modify. The plugin then uses these field values:

Block with modal plugins helper