Index
Edit

Block

To make a rich text field in sanity, you must make an array of blocks. In the schema it looks like this in its simplest form:

{
  title: 'Text', 
  name: 'text',
  type: 'array', 
  of: [{type: 'block'}]
}

In Sanity, Rich Text is modelled as an array of content instead of HTML. 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, or other formats depending on the target requirements. Not only does this keep the content clean, it also provides a lot of flexibility if you want to re-use content across web, apps, print, set-top-boxes, consoles, etc.

The block text type supports block styles, lists, decorators (bold, italic, etc.), embedded objects, inline objects, and even marking up text with arbitrary object data.

Properties

typestring

Required. Value must be set to block. Also, blocks only make sense as member of an array, see examples below.

stylesarray

This defines which styles that applies to blocks. A style is an object with a title (will be displayed in the style dropdown) and a value, e.g.: styles: {title: 'Quote', value: 'quote'}. If no styles are given, the default styles are H1 up to H6 and quote. A style named normal is reserved, always included and represents "unstyled" text. If you don't want any styles, set this to an empty array e.g.: styles: [].

listsarray

What list types that can be applied to blocks. Like styles above, this also is an array of "name", "title" pairs, e.g.: {title: 'Bullet', value: 'bullet'}. Default list types are bullet and number.

marksobject

An object defining which .decorators (array) and .annotations (array) are allowed. See example below.

titlestring

Human readable label for the field.

namestring

Required. The field name. This will be the key in the data record.

hiddenboolean

If set to true, this field will be hidden in the Content Studio.

readOnlyboolean

If set to true, this field will not be editable in the content studio.

descriptionstring

Short description to editors how the field is to be used.

Gotcha

A block represents a single paragraph. To make sense, your blocks must live inside an array.

Example schema: Default block array

With no custom configuration, the block editor supports:

  • Block styles: Heading 1 to Heading 6, Quotes
  • Decorators: Strong, emphasis, code, underline and strikethrough
  • Lists: bullet list and ordered list
  • Link: An annotation that is an object with a href with type: url
Schema
{
  title: 'Rich text example',
  name: 'myRichTextExample',
  type: 'array',
  of: [{type: 'block'}]
}
JSON output
{
  "myRichTextExample": [{
    "style": "normal",
    "_type": "block",
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "text": "That was ",
        "marks": []
      },
      {
        "_type": "span",
        "text": "bold",
        "marks": [
          "strong"
        ]
      },
      {
        "_type": "span",
        "text": " of you.",
        "marks": []
      }
    ]
  },
  {
    "style": "normal",
    "_type": "block",
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "text": "Amazing, actually.",
        "marks": []
      }
    ]
  }]
}

Example schema: Block array with custom types

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'}
  ]
}

The editor will now get an "Insert"-button in the text editor where they can insert actors or images as content blocks in their 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. Use the option inline to have the object appear in this manner:

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

Customizing

Almost every aspect of the block editor and the content it produces is configurable. You may want to restrict certain types of decorators or add your own, use your own list styles, annotate text with custom data (e.g. a citation or reference), or support highlighted text.

Example schema: Block array with custom types

{
  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'}}
        ]
      }
    }
  ]
}
Pro-tip

Are you subconsciously wondering how to write a GROQ query to search for the occurence of a string in an array of blocks? Try *[body[].children[].text match "aliens"].

See also

Previous: ArrayNext: Span