# Block parameters or fields

> Blocks allow for repeatable content structures to be managed on components and entries.

Source: https://docs.uniform.app/docs/guides/models/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).

```mermaid
flowchart TD
  A["Entry (Product)"]
  A --> F["Block field: Product options"]
  F -- "contains" --> B1["Block: Product option"]
  F -- "contains" --> B2["Block: Product option"]
  F -- "contains" --> B3["Block: Product option"]
  B1 --> C1["Field: Size"]
  B1 --> C2["Field: Color"]
  B2 --> C3["Field: Size"]
  B2 --> C4["Field: Color"]
  B3 --> C5["Field: Size"]
  B3 --> C6["Field: Color"]

  %% Reference field branch
  A --> RF["Reference field: Product category"]
  RF -. "references" .-> RC["Product category entry"]

  %% Color coding
  style F fill:#fff9c4,stroke:#fbc02d
  style B1 fill:#fff9c4,stroke:#fbc02d
  style B2 fill:#fff9c4,stroke:#fbc02d
  style B3 fill:#fff9c4,stroke:#fbc02d
  style C1 fill:#f8bbd0,stroke:#c2185b
  style C2 fill:#f8bbd0,stroke:#c2185b
  style C3 fill:#f8bbd0,stroke:#c2185b
  style C4 fill:#f8bbd0,stroke:#c2185b
  style C5 fill:#f8bbd0,stroke:#c2185b
  style C6 fill:#f8bbd0,stroke:#c2185b
  style RF fill:#b3e5fc,stroke:#0288d1
  style RC fill:#b3e5fc,stroke:#0288d1
  style A fill:#e0f7fa,stroke:#00796b
```

## 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](#nested-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](https://docs.uniform.app/docs/guides/patterns/component-patterns#pattern-overrides). 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**](https://docs.uniform.app/docs/guides/models/content-types/references) 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**](https://docs.uniform.app/docs/guides/models/components/parameters#group-parameters).

### Decision table

| Use case | Blocks | Reference fields | Field groups |
| --- | --- | --- | --- |
| Repeatable set of fields within a single entry (`1:n` relationship, content not reused) | ✅ yes | ❌ no | ❌ no |
| Same set of fields reused across multiple content types (`1:1` relationship, schema reuse only) | ✅ yes | ❌ no | ❌ no |
| Same content reused across multiple entries (`1:n` or `n:n` relationship, content reuse) | ❌ no | ✅ yes | ❌ no |
| Content needs independent publishing/lifecycle | ❌ no | ✅ yes | ❌ no |
| Non-repeatable, non-reusable fields within a single entry (`1:1` relationship, no reuse) | ❌ no | ❌ no | ✅ yes |

## Use blocks in components

While blocks can be used in components to model repeatable sets of fields, in most cases you should use [slots](https://docs.uniform.app/docs/guides/models/components#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](https://docs.uniform.app/docs/guides/personalization/canvas-personalization) and [A/B testing](https://docs.uniform.app/docs/guides/ab-testing).
- Components in slots can have [visibility controls](https://docs.uniform.app/docs/guides/composition/conditional-logic/component-visibility-control) to show or hide them based on conditions.
- Parameters of components in slots can be overridden in [component patterns](https://docs.uniform.app/docs/guides/patterns/component-patterns).
- In component patterns, you add components to a slot using [slot sections](https://docs.uniform.app/docs/guides/patterns/component-patterns#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

> **Model and fill in blocks with Scout or MCP:**
>
> [Scout](https://docs.uniform.app/docs/guides/ai/scout) and the [Uniform MCP server](https://docs.uniform.app/docs/guides/ai/mcp-server) can manage block types and content in blocks. See [Scout capabilities and limitations](https://docs.uniform.app/docs/guides/ai/scout/use-cases-and-capabilities#content-modeling).

### Create a block type

The first step in using blocks is to create one.

1. Navigate to **Experience > Content Types** and click **Add content type**, then 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](https://docs.uniform.app/docs/guides/models/content-types/fields) or to a **component** as [parameters](https://docs.uniform.app/docs/guides/models/components/parameters).

Refer to documentation for [Block parameters and fields](https://docs.uniform.app/docs/guides/models/components/parameters#blocks) 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.](https://docs.uniform.app/images/guides/models/nested-blocks.png)

> **Don't nest blocks too deeply:**
>
> While there are no limits on how deeply you can nest blocks, we recommend to not exceed 2 levels. It will become more difficult to find the right content to edit when you need to drill down through multiple levels of nested blocks.

### Loops in blocks

[Loops](https://docs.uniform.app/docs/guides/composition/connect-external-data/loop-component) can be used in blocks if you want to connect the block field to pull in an array of structured data from a data resource. For example, you might want to pull in the product variants of a Product entry from an external 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](https://docs.uniform.app/images/guides/models/loops-in-blocks.png)

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](https://docs.uniform.app/images/guides/models/allow-loop-in-block-field.png)