Blocks Field

The Blocks field represents a list of items, similar to the Group List field, but allows each entity in the list to have a unique shape.

For an in-depth explanation of the Blocks field, read our "What are Blocks?" blog post. To see a real-world example of Blocks in use, check out the Tina Grande Starter.

In the gif above, you see a list of Blocks: Title, Image, and Content. The form for this field could be configured like this:

const PageForm = {
  label: 'Page',
  fields: [
    {
      label: 'Page Sections',
      name: 'rawJson.blocks',
      component: 'blocks',
      templates: {
        TitleBlock,
        ImageBlock,
        ContentBlock,
      },
    },
  ],
}

Each of the templates in this configuration represent a configuration object that looks more or less like a top-level form configuration object.

/*
 **  Block template definition for the content block
 **/
export const ContentBlock = {
  label: 'Content',
  key: 'content-block',
  defaultItem: {
    content: '',
  },
  fields: [{ name: 'content', label: 'Content', component: 'markdown' }],
}

The source data for the ContentBlock might look like the example below. When new blocks are added, additional JSON objects will be added to the blocks array:

{
  "blocks": [
    {
      "content": "**Billions upon billions** are creatures of the cosmos Orion's sword cosmic fugue at the edge of forever science?"
    }
  ]
}

Blocks Field Options

• name: The path to the blocks value in the data being edited.
• component: The name of the React component that should be used to edit this field. Available field component types are defined here.
• label: A human readable label for the field. This label displays in the sidebar and is optional. If no label is provided, the sidebar will default to the name.
• description: An optional description of the field.
• templates: A list of Block templates that define the fields used in the Blocks.

Block Template Options

• label: A human readable label for the Block.
• key: Should be unique to optimize the rendering of the list.
• fields: An array of fields that will render as a sub-menu for each block. The fields should map to editable content.
• defaultItem: An optional function to provide the block with default data upon being created.
• itemProps: An optional function that generates props for each group item.
  • key: This property is used to optimize the rendering of lists. If rendering is causing problems, use defaultItem to generate a new key, as is seen in this example. Feel free to reference the React documentation for more on keys and lists.
  • label: A readable label for the new Block.

Interfaces

import { Field } from '@tinacms/core'

interface BlocksConfig {
  name: string
  component: 'blocks'
  label?: string
  description?: string
  templates: {
    [key: string]: BlockTemplate
}

interface BlockTemplate {
  label: string
  key: string
  fields: Field[]
  defaultItem?: object | (() => object)
  itemProps?: (
    item: object
  ) => {
    key?: string
    label?: string
  }
}