Block Text

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 semantics of 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, brochures, books, etc.

To enable rich text editing, all you need to do is to define an array that contains a block type. A block is a special type that can contain data associated with rich text, like lists, headings and pullquotes.

Additionally, another special type span is used to represent the actual text content within that block.

Example schema: Block Array with defaults

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
  title: 'Rich text example',
  name: myRichTextExample
  type: 'array',
  of: [{type: 'block'}]

Example schema: Block Array with custom types

This defines a block array that can include both text, actors and (inline) images. Making a custom type inline in the text is just a matter of setting the option inline: true for that type within the of array.

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

Customizing blocks / spans

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 with customizations

  name: 'customized',
  title: 'Customized block type',
  type: 'array',
  of: [
      type: 'block',
      // Only allow these 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'}}



  • 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.
  • marks: object - An object defining which .decorators (array) and .annotations (array) are allowed (see example above).


No special options are defined for Block.

Previous: ArrayNext: Span