Block types
A block type is a kind of section: a hero, a feature grid, a call to action. It declares the fields an editor fills in.
Adding one
Under Model → Blocks:
- New block — give it an API id and a label. The API id is what your site's registry uses (
brand-hero), the label is what editors see ("Brand hero"). - Add fields. Each has a key, a label, and a type.
- Save.
- Allow it on the content types that should offer it, under Model → Content types.
The block will not be usable in published content until the site has a component for it and its registry has been refreshed. See The registry manifest.
Fields
| Property | Effect |
|---|---|
| Key | How the field is addressed in the API and in your component: fields.title. |
| Label | What editors see. Falls back to the key. |
| Type | Which editor the field gets. See Field types. |
| Required | Content cannot be published while this is empty. |
| Localized | The field has a separate value per language. |
| Help | A sentence under the field in the editor. |
Order matters
Fields are shown to editors in the order you list them, so put the important ones first: what someone fills in every time before what they fill in occasionally. Use the arrows to reorder.
Required is enforced
A required field is not a hint. The CMS refuses to publish a release whose blocks leave one empty, and empty means empty: an empty string, an empty list and an empty object all count.
Mark a field required when your component would break or look wrong without it. A hero with no title is a broken hero; a hero with no eyebrow is fine.
Do not mark everything required. Every required field is a thing that can block a publish at the worst moment, so spend them where a missing value actually causes damage.
Localized
Turn this on for text that differs per language. Leave it off for things that do not: an image, a colour, a link to an external site.
Naming fields
Field keys are read by developers and appear in your component. Use what the field is, not where it currently appears:
| Prefer | Avoid |
|---|---|
title | bigTextTop |
ctaHref | blueButtonLink |
items | threeThings |
threeThings is the classic mistake: the day someone wants four, the field's name is a lie.
Changing an existing block type
Changing a block type affects every document already using it.
Adding a field is safe. Existing documents simply have it empty.
Removing a field loses that content on every document using the block. The value stays in the document until it is next saved, but nothing shows it and your component should stop reading it.
Renaming a key is a remove plus an add: content does not move across, and your component must change in the same deploy.
Marking an existing field required can block publishing straight away, because documents that already leave it empty now fail the check. Fill them first, then mark it.
Variations
A block type can declare variations: named presets your component reads to render the same content differently — a feature grid as cards, as a plain list, as a timeline.
Use a variation when the content is identical and only the presentation changes. When the fields differ, that is a different block type.