Block

Schema type for block which provides a rich text editor for block content.

The block type is the basis for Sanity's Portable Text editor. See the BlockDefinition reference for the full type definition.

To activate the Portable Text editor, define an array of blocks. In the schema, it looks like this in its simplest form:

{
  title: 'Content', 
  name: 'content',
  type: 'array', 
  of: [{type: 'block'}]
}

In other words, rich text is modeled as an array of content following the specification for Portable Text. What is stored in the database is an array of JSON objects describing the rich text content. This JSON data can later be used to produce HTML, React components, or other formats depending on the target requirements. This provides a lot of flexibility if you should later want to re-use your content across the web, apps, print, set-top-boxes, consoles, etc.

The block type supports block styles, lists, decorators (bold, italic, and so on), custom content types (embedded objects), inline objects, and marking up text with arbitrary object data (annotations). Learn more about how to configure the Portable Text editor.

A block declaration accepts only the properties in this table. Any other key makes the schema invalid with the error Found unknown properties for block declaration. Notably, icon, description, hidden, readOnly, deprecated and initialValue are not supported on a block, even though TypeScript accepts several of them. Set those on the enclosing array field instead.

Declaring styles, lists, marks.decorators or marks.annotations replaces that default set rather than extending it, so any built-in you leave out is gone. Each defaults independently: if you declare marks.decorators and omit marks.annotations, the default link annotation is still there, and the reverse is also true.

Set these under the block’s options key. See BlockOptions for the full type definition.

Build these with the rule builder passed to validation. See BlockRule for the full type definition.

With no custom configuration, the Portable Text editor supports:

• Block styles: Normal, Heading 1 to Heading 6, and blockquotes

Decorators: Strong, Italic, Code, Underline and Strike, with the values strong, em, code, underline and strike-through

• Lists: bullet list and ordered list
• Link: An annotation that is an object with a href with type url

Input

{
  title: 'Rich text example',
  name: 'myRichTextExample',
  type: 'array',
  of: [{type: 'block'}]
}

Response

{
  "myRichTextExample": [
    {
      "_key": "9d2d1ed68d84",
      "_type": "block",
      "style": "normal",
      "children": [
        {
          "_key": "a1f4c2d90b31",
          "_type": "span",
          "marks": [],
          "text": "I am "
        },
        {
          "_key": "b7e5d3a81c42",
          "_type": "span",
          "marks": [
            "strong"
          ],
          "text": "strong and "
        },
        {
          "_key": "c8f6e4b92d53",
          "_type": "span",
          "marks": [
            "strong",
            "cbe9d12c6af9"
          ],
          "text": "annotated"
        }
      ],
      "markDefs": [
        {
          "_key": "cbe9d12c6af9",
          "_type": "link",
          "href": "https://example.com/annotations"
        }
      ]
    },
    {
      "_key": "4b0e7a2c8d15",
      "_type": "block",
      "style": "normal",
      "markDefs": [],
      "children": [
        {
          "_key": "e2c9f1a63b74",
          "_type": "span",
          "marks": [],
          "text": "Amazing, actually."
        }
      ]
    }
  ]
}

This defines a block array that can include both text, actors, and (inline) images.

{
  title: 'Rich text',
  type: 'array',
  of: [
    {type: 'block'},
    {type: 'actor'},
    {type: 'image', icon: myIcon}
  ]
}

The editor will now get an insertion (+) icon in the text editor that can be used to insert actors or images as content blocks in the text. The data stored in the array for these objects are exactly as if they were in a regular array of objects, because they are.

These objects are embedded on the block level, but you may also need objects that appear inline with text useful for stuff like footnotes, ticker-symbols or sparklines. Add these to an array under the of key in the block type object:

{
  title: 'Rich text',
  type: 'array',
  of: [
    {
      type: 'block',
      of: [
        {type: 'footnote'}
      ]
    }
  ]
}

Almost every aspect of the Portable Text editor and the content it produces is configurable. You may want to restrict certain decorators or add your own, use your own list styles, annotate text with custom data such as a citation or reference, or support highlighted text.

A style, decorator, list or annotation can take a component property, a callback that controls how that mark is rendered in the studio, and an icon property for its button in the editor toolbar. On the block itself, neither key is valid: use components (plural) for the block’s own render overrides.

{
  name: 'customized',
  title: 'Customized block type',
  type: 'array',
  of: [
    {
      type: 'block',
      // ...
      marks: {
        decorators: [
          { title: "Strong", value: "strong" },
          { title: "Emphasis", value: "em" },
          {
            title: "Sup",
            value: "sup",
            icon: () => <div>x<sup>2</sup></div>,
            component: ({ children }) => <sup>{children}</sup>
          },
        ],
      },
      // ...
    }
  ]
}

This declares decorators only, so it replaces the five default decorators with these three and drops Code, Underline and Strike. Because annotations is not declared, the default link annotation is untouched and still available in the editor.

{
  name: 'customized',
  title: 'Customized block type',
  type: 'array',
  of: [
    {
      type: 'block',
      // Only allow these block styles
      styles: [
        {title: 'Normal', value: 'normal'},
        {title: 'H1', value: 'h1'},
        {title: 'H2', value: 'h2'}
      ],
      // Only allow numbered lists
      lists: [
        {title: 'Numbered', value: 'number'}
      ],
      marks: {
        // Only allow these decorators
        decorators: [
          {title: 'Strong', value: 'strong'},
          {title: 'Emphasis', value: 'em'}
        ],
        // Support annotating text with a reference to an author
        annotations: [
          {name: 'author', title: 'Author', type: 'reference', to: {type: 'author'}}
        ]
      }
    }
  ]
}