Blocks

Introduction to blocks#

Blocks in Uniform organize sets of fields that repeat within a parent entry, such as listing different product options or store opening hours. This keeps related content together and avoids cluttering your project with extra entries.

The diagram below shows how a block field and a reference field organize content within a product entry. Block fields contain repeatable blocks (owned content), while reference fields point to separate entries (referenced content).

Characteristics of blocks#

• Repeatable set of fields: Blocks allow you to define a set of fields that can be repeated within a parent entry.
• Always tied to a parent entry: Blocks cannot exist on their own; they are always part of another content type or component.
• Not reusable outside the parent: The content in a block is only relevant to its parent and is not referenced elsewhere.
• Follow the parent's lifecycle: Blocks are published, unpublished, and deleted together with their parent entry.
• Can be nested: Blocks can contain other blocks
• Inherits access permissions: Blocks share the same access permissions as their parent entry.

Typical use cases for blocks#

• Product variants (e.g., size, color options)
• Opening hours (e.g., Monday–Friday, 9am–5pm)
• Feature lists (e.g., product-specific features)
• Price breakdowns (e.g., multiple price tiers, currencies)
• SEO or Open Graph metadata (when fields are reused across content types)

Limitations of blocks#

Be aware of the following limitations when using blocks:

• Block fields do not support overrides in patterns. This means you cannot change block field values on a per-pattern-instance basis.
• The number of blocks in a block field cannot be localized. While the fields inside each block can be localized, the total number of blocks will always be the same across all locales.

Use blocks in content types#

Use blocks when you need a repeatable set of fields within a parent entry, and the content is only relevant in the context of that parent.

Blocks are also ideal for reusing sets of fields when the same fields are needed in multiple content types (e.g. SEO or Open Graph metadata).

When not to use blocks (and what to use instead)#

• If the content needs to be reused or referenced in multiple places, use a reference field instead.
• If you just need a one-off set of related fields that is not repeatable and specific to a single content type, use a field group.

Decision table#

Use blocks in components#

While blocks can be used in components to model repeatable sets of fields, in most cases you should use slots instead. Slots provide greater flexibility and enable advanced features that are not possible with blocks alone.

Advantages of using slots in components:

• Components placed in slots are rendered automatically and their appearance can be changed without developer intervention. If a block is used in a component, then it requires custom code for rendering the block.
• Components in slots can be used for personalization and A/B testing.
• Components in slots can have visibility controls to show or hide them based on conditions.
• Parameters of components in slots can be overridden in component patterns.
• In component patterns, you add components to a slot using slot sections.

When to use a block in a component:

In some specific cases, using a block parameter on a component can be useful:

• If the content from the block is not represented by a visual component such as metadata or configuration options for a component.
• If you need to pass an array of structured data to a component that implements custom rendering logic that is not possible with slots.

Manage blocks#

Create a block type#

The first step in using blocks is to create one.

1. Navigate to Experience > Content types and select Add content type and choose Block type from the dropdown.
2. Enter your information in the fields presented as necessary for the block you are trying to create.
3. Add what field or fields you need for your model. You can add any field type to a block type.
4. Click Accept on the bottom of the dialog to update the block type configuration. To add a new field you can also select Accept and add another option in the button dropdown.
5. After all the block type updates are complete, make sure to save the block type to apply your changes.

Next, you'll add the block to a content type or component.

Add block to content type or component#

Blocks can be added to content types as fields or to a component as parameters.

Refer to documentation for Block parameters and fields for information on how to add a block to a content type or component.

Nested blocks#

Blocks can also be nested to allow for structures where elements are grouped. For example, in a recipe, you could use a block to represent each step in the instructions, and within each step, a nested block for sub-steps or for listing the specific ingredients needed for that step.

A block containing additional, nested blocks.

Loops in blocks#

Loops can be used in blocks if you want to connect the block field to pull in an array of structured data from an data resource. For example, you might want to pull in the product variants of an Product entry from an eternal product information management system (PIM) and connect the properties of the variants to a "Product Variant" block type.

A block containing a loop with product variants

To be able to insert the loop component into a block field you need to enable it in the "Allowed types" settings of the block field or parameter.

Enabling the loop component for a block field