Slate Rich Text

The Slate editor has been supported by Payload since we released our initial beta. It's battle-tested and will continue to be supported into the future.

If you are migrating a Payload project from 1.x or earlier, you can continue to use the Slate editor as long as you'd like.

To use the Slate editor, first you need to install it:

1npm install --save @payloadcms/richtext-slate

After installation, you can pass it to your top-level Payload config:

1import { buildConfig } from 'payload/config'
2import { slateEditor } from '@payloadcms/richtext-slate'
3
4export default buildConfig({
5  collections: [
6    // your collections here
7  ],
8  // Pass the Slate editor to the root config
9  editor: slateEditor({})
10})

And here's an example for how to install the Slate editor on a field-by-field basis, while customizing its options:

1import { CollectionConfig } from 'payload/types'
2import { slateEditor } from '@payloadcms/richtext-slate'
3
4export const Pages: CollectionConfig = {
slug: 'pages',
fields: [
  {
    name: 'content',
    type: 'richText',
    // Pass the Slate editor here and configure it accordingly
    editor: slateEditor({
      admin: {
        elements: [
          // customize elements allowed in Slate editor here
        ],
        leaves: [
          // customize leaves allowed in Slate editor here
        ]
      }
    })
  }
]
23}

Admin Options

elements

The elements property is used to specify which built-in or custom SlateJS elements should be made available to the field within the admin panel.

The default elements available in Payload are:

h1
h2
h3
h4
h5
h6
blockquote
link
ol
ul
textAlign
indent
relationship
upload
textAlign

leaves

The leaves property specifies built-in or custom SlateJS leaves to be enabled within the Admin panel.

The default leaves available in Payload are:

bold
code
italic
strikethrough
underline

link.fields

This allows fields to be saved as extra fields on a link inside the Rich Text Editor. When this is present, the fields will render inside a modal that can be opened by clicking the "edit" button on the link element.

link.fields may either be an array of fields (in which case all fields defined in it will be appended below the default fields) or a function that accepts the default fields as only argument and returns an array defining the entirety of fields to be used (thus providing a mechanism of overriding the default fields).

RichText link fields RichText link with custom fields

upload.collections[collection-name].fields

This allows fields to be saved as meta data on an upload field inside the Rich Text Editor. When this is present, the fields will render inside a modal that can be opened by clicking the "edit" button on the upload element.

RichText upload element RichText field using the upload element

RichText upload element modal displaying fields from the config

Relationship element

The built-in relationship element is a powerful way to reference other Documents directly within your Rich Text editor.

Upload element

Similar to the relationship element, the upload element is a user-friendly way to reference Upload-enabled collections with a UI specifically designed for media / image-based uploads.

Relationship and Upload elements are populated dynamically into your Rich Text field' content. Within the REST and Local APIs, any present RichText relationship or upload elements will respect the depth option that you pass, and will be populated accordingly. In GraphQL, each richText field accepts an argument of depth for you to utilize.

TextAlign element

Text Alignment is not included by default and can be added to a Rich Text Editor by adding textAlign to the list of elements. TextAlign will alter the existing element to include a new textAlign field in the resulting JSON. This field can be used in combination with other elements and leaves to position content to the left, center or right.

Specifying which elements and leaves to allow

To specify which default elements or leaves should be allowed to be used for this field, define arrays that contain string names for each element or leaf you wish to enable. To specify a custom element or leaf, pass an object with all corresponding properties as outlined below. View the example to reference how this all works.

Building custom elements and leaves

You can design and build your own Slate elements and leaves to extend the editor with your own functionality. To do so, first start by reading the SlateJS documentation and looking at the Slate examples to familiarize yourself with the SlateJS editor as a whole.

Once you're up to speed with the general concepts involved, you can pass in your own elements and leaves to your field's admin config.

Both custom elements and leaves are defined via the following config:

Property	Description
`name` *	The default name to be used as a `type` for this element.
`Button` *	A React component to be rendered in the Rich Text toolbar.
`plugins`	An array of plugins to provide to the Rich Text editor.
`type`	A type that overrides the default type used by `name`

Custom Elements also require the Element property set to a React component to be rendered as the Element within the rich text editor itself.

Custom Leaf objects follow a similar pattern but require you to define the Leaf property instead.

Specifying custom Types let you extend your custom elements by adding additional fields to your JSON object.

Example

collections/ExampleCollection.ts

1import type { CollectionConfig } from 'payload/types'
2
3import { slateEditor } from '@payloadcms/richtext-slate'
4
5export const ExampleCollection: CollectionConfig = {
slug: 'example-collection',
fields: [
  {
    name: 'content', // required
    type: 'richText', // required
    defaultValue: [
      {
        children: [{ text: 'Here is some default content for this field' }],
      },
    ],
    required: true,
    editor: slateEditor({
      admin: {
        elements: [
          'h2',
          'h3',
          'h4',
          'link',
          'blockquote',
          {
            name: 'cta',
            Button: CustomCallToActionButton,
            Element: CustomCallToActionElement,
            plugins: [
              // any plugins that are required by this element go here
            ],
          },
        ],
        leaves: [
          'bold',
          'italic',
          {
            name: 'highlight',
            Button: CustomHighlightButton,
            Leaf: CustomHighlightLeaf,
            plugins: [
              // any plugins that are required by this leaf go here
            ],
          },
        ],
        link: {
          // Inject your own fields into the Link element
          fields: [
            {
              name: 'rel',
              label: 'Rel Attribute',
              type: 'select',
              hasMany: true,
              options: ['noopener', 'noreferrer', 'nofollow'],
            },
          ],
        },
        upload: {
          collections: {
            media: {
              fields: [
                // any fields that you would like to save
                // on an upload element in the `media` collection
              ],
            },
          },
        },
      },
    }),
  },
],
72}

Generating HTML

As the Rich Text field saves its content in a JSON format, you'll need to render it as HTML yourself. Here is an example for how to generate JSX / HTML from Rich Text content:

1import React, { Fragment } from "react";
2import escapeHTML from "escape-html";
3import { Text } from "slate";
4
5const serialize = (children) =>
children.map((node, i) => {
  if (Text.isText(node)) {
    let text = (
      <span dangerouslySetInnerHTML={{ __html: escapeHTML(node.text) }} />
    );
11
    if (node.bold) {
      text = <strong key={i}>{text}</strong>;
    }
15
    if (node.code) {
      text = <code key={i}>{text}</code>;
    }
19
    if (node.italic) {
      text = <em key={i}>{text}</em>;
    }
23
    if (node.text === '') {
      text = <br />;
    }
27
    // Handle other leaf types here...
29
    return <Fragment key={i}>{text}</Fragment>;
  }
32
  if (!node) {
    return null;
  }
36
  switch (node.type) {
    case "h1":
      return <h1 key={i}>{serialize(node.children)}</h1>;
    // Iterate through all headings here...
    case "h6":
      return <h6 key={i}>{serialize(node.children)}</h6>;
    case "blockquote":
      return <blockquote key={i}>{serialize(node.children)}</blockquote>;
    case "ul":
      return <ul key={i}>{serialize(node.children)}</ul>;
    case "ol":
      return <ol key={i}>{serialize(node.children)}</ol>;
    case "li":
      return <li key={i}>{serialize(node.children)}</li>;
    case "link":
      return (
        <a href={escapeHTML(node.url)} key={i}>
          {serialize(node.children)}
        </a>
      );
57
    default:
      return <p key={i}>{serialize(node.children)}</p>;
  }
});

Built-in SlateJS Plugins

Payload comes with a few built-in SlateJS plugins which can be extended to make developing your own elements and leaves a bit easier.

`shouldBreakOutOnEnter`

Payload's built-in heading elements all allow a "hard return" to "break out" of the currently active element. For example, if you hit enter while typing an h1, the h1 will be "broken out of" and you'll be able to continue writing as the default paragraph element.

If you want to utilize this functionality within your own custom elements, you can do so by adding a custom plugin to your element like the following "large body" element example:

customLargeBodyElement.js:

1import Button from './Button'
2import Element from './Element'
3import withLargeBody from './plugin'
4
5export default {
6  name: 'large-body',
7  Button,
8  Element,
9  plugins: [
10    (incomingEditor) => {
11      const editor = incomingEditor
12      const { shouldBreakOutOnEnter } = editor
13
14      editor.shouldBreakOutOnEnter = (element) =>
15        element.type === 'large-body' ? true : shouldBreakOutOnEnter(element)
16
17      return editor
18    },
19  ],
20}

Above, you can see that we are creating a custom SlateJS element with a name of large-body. This might render a slightly larger body copy on the frontend of your app(s). We pass it a name, button, and element—but additionally, we pass it a plugins array containing a single SlateJS plugin.

The plugin itself extends Payload's built-in shouldBreakOutOnEnter Slate function to add its own element name to the list of elements that should "break out" when the enter key is pressed.

TypeScript

If you are building your own custom Rich Text elements or leaves, you may benefit from importing the following types:

1import type { RichTextCustomElement, RichTextCustomLeaf } from '@payloadcms/richtext-slate'

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.