The Blocks Field is incredibly powerful, storing an array of objects based on the fields that your define, where each item in the array is a "block" with its own unique schema.
Blocks are a great way to create a flexible content model that can be used to build a wide variety of content types, including:
Quote
, CallToAction
, Slider
, Content
, Gallery
, or others.Text
, Select
, or Checkbox
.Break
, a Presentation
, or a BreakoutSession
.To add a Blocks Field, set the type
to blocks
in your Field Config:
Option | Description |
---|---|
name * | To be used as the property name when stored and retrieved from the database. More |
label | Text used as the heading in the Admin Panel or an object with keys for each language. Auto-generated from name if not defined. |
blocks * | Array of block configs to be made available to this field. |
validate | Provide a custom validation function that will be executed on both the Admin Panel and the backend. More |
minRows | A number for the fewest allowed items during validation when a value is present. |
maxRows | A number for the most allowed items during validation when a value is present. |
saveToJWT | If this field is top-level and nested in a config supporting Authentication, include its data in the user JWT. |
hooks | Provide Field Hooks to control logic for this field. More details. |
access | Provide Field Access Control to denote what users can see and do with this field's data. More details. |
hidden | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API response or the Admin Panel. |
defaultValue | Provide an array of block data to be used for this field's default value. More |
localized | Enable localization for this field. Requires localization to be enabled in the Base config. If enabled, a separate, localized set of all data within this field will be kept, so there is no need to specify each nested field as localized . |
unique | Enforce that each entry in the Collection has a unique value for this field. |
labels | Customize the block row labels appearing in the Admin dashboard. |
admin | Admin-specific configuration. More details. |
custom | Extension point for adding custom data (e.g. for plugins) |
typescriptSchema | Override field type generation with providing a JSON schema |
* An asterisk denotes that a property is required.
The customize the appearance and behavior of the Blocks Field in the Admin Panel, you can use the admin
option:
The Blocks Field inherits all of the default options from the base Field Admin Config, plus the following additional options:
Option | Description |
---|---|
initCollapsed | Set the initial collapsed state |
isSortable | Disable order sorting by setting this value to false |
Blocks are defined as separate configs of their own.
Option | Description |
---|---|
slug * | Identifier for this block type. Will be saved on each block as the blockType property. |
fields * | Array of fields to be stored in this block. |
labels | Customize the block labels that appear in the Admin dashboard. Auto-generated from slug if not defined. |
imageURL | Provide a custom image thumbnail to help editors identify this block in the Admin UI. |
imageAltText | Customize this block's image thumbnail alt text. |
interfaceName | Create a top level, reusable Typescript interface & GraphQL type. |
graphQL.singularName | Text to use for the GraphQL schema name. Auto-generated from slug if not defined. NOTE: this is set for deprecation, prefer interfaceName . |
dbName | Custom table name for this block type when using SQL Database Adapter (Postgres). Auto-generated from slug if not defined. |
custom | Extension point for adding custom data (e.g. for plugins) |
In addition to the field data that you define on each block, Payload will store two additional properties on each block:
blockType
The blockType
is saved as the slug of the block that has been selected.
blockName
The Admin Panel provides each block with a blockName
field which optionally allows editors to label their blocks for better editability and readability.
collections/ExampleCollection.js
As you build your own Block configs, you might want to store them in separate files but retain typing accordingly. To do so, you can import and use Payload's Block
type: