Blocks

In Storyblok, a block is a piece of content. A block can be an entire entry (a story), or it can be just one piece of an entry.

There are three categories of blocks:

• Content type
• Nestable
• Universal

Content type blocks are stories. An example of a content type block would be a post, article, or page. Every blank Storyblok space comes with a page content type.

Nestable blocks are children of other blocks. An example of a nestable block would be text, image, or hero. They are dynamic building blocks used to create rich content layouts.

Universal blocks can be used as both content type blocks and nestable blocks. An example of a universal block is a CTA, which can be used as a standalone story and an element on a page.

Tip

To learn how to create and manage content, edit blocks, and add presets with pre-filled content, check the Visual Editor manual.

All blocks in a space are listed in the Block Library. Use folders and tags to organize blocks or control access within the editor.

To create a new block, open the Block Library, select + New Block, and choose the type.

Add fields

To add blocks to any content type, open Fields and add a Blocks field.

Storyblok supports many other fields you can use to compose blocks. To learn more, check the Fields documentation.

Delete fields

To delete a field, open the Block Library, select the relevant block, open Fields, and choose Remove Field.

Deleting a field from the schema retains the existing values. Stories that contain a value associated with the deleted field display the message 1 item out of schema in the Visual Editor.

Select the message and decide how to proceed:

• Add field: restores the field.
• Delete field: deletes the stored value.

To clear leftover values in multiple stories at once, use Storyblok CLI’s migrations commands:

1. Migrate the block with migrations generate.
2. Delete the field from the generated function.
3. Apply it with migrations run.

The run takes a snapshot beforehand, so you can revert the action with migrations rollback.

Set name

The Technical name is listed as the value of the component (block) key in the API response.

Danger

The word “content” is a reserved keyword. Only use it as a block’s technical name when combined with other characters.

The Technical name also serves as the Display name if one isn’t provided.

Caution

Changes to the Technical name may take a few minutes to propagate. Notify editors before making the change. When using branches, the updated name first appears only in the preview branch.

The Display name is visible in the editor. To help users quickly recognize it, pick a short and descriptive name.

The Description provides additional information about the block. A brief, clear description lets users understand the block’s use case.

Create previews

Blocks support a preview field that appears in the overview, and a screenshot that appears when editors select the block in the editor.

By default, the overview shows the value of the block’s first text field. To preview a different field, choose Use for preview in that field’s advanced options. For complete control over the line, define a preview template.

Blocks can include preview templates based on the Squirrelly 8 templating language. Below is an example snippet:

<div>{{it.text}}</div>
{{@image(it.image.filename)/}}

All block fields are available on the it object. The preview template support div, span, strong, ul, li, and p HTML tags, as well as class attributes.

<div class="text-red">{{it.error}}</div>

The following Squirrelly helpers are available:

• @image()
• @it()
• @each()
• @foreach()

Data from linked stories isn’t available in preview templates.

Share blocks across spaces

Three approaches keep block schemas consistent across spaces:

The Storyblok CLI

The Storyblok CLI transfers schemas on demand. The components pull and components push commands move blocks between spaces as JSON files. This approach keeps each space independent and allows storing schemas in version control. To keep spaces aligned automatically, run the commands from a CI/CD pipeline.

The CLI also supports a code-first approach: define the schema once with @storyblok/schema and apply it to every space with schema push. The TypeScript definition becomes the source of truth, the command prints a diff before applying, and each push records the previous state so schema rollback can revert the change. To adopt an existing space, run schema init, and generate the definition from this space.

The shared components app

The Shared components app links spaces in a parent-child structure. Each child space references the parent space’s ID in its settings and inherits the parent’s schemas. Once linked, a change in the parent’s block library automatically updates every child space. Linked spaces have an identical schema configuration, and child spaces no longer maintain a block library.

View history

Every block has a version history, which records the changes made to it over time. To view it, open the Block library, select the relevant block, and open Versions.

Each entry records when the change happened and who made it. Preview a version to check its schema, then restore it to make it the current version.

Related resources

Components in the Management API

Component Folders in the Management API