---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.3
alternate:
  - https://divkit.tech/docs/en/concepts/item_builder.md
  - https://divkit.tech/docs/ru/concepts/item_builder.md
---
> **Documentation Index:** Fetch the complete configuration index at https://divkit.tech/docs/en/llms.txt

# Containers with a dynamic dataset

In DivKit, you can create [containers](https://divkit.tech/docs/en/concepts/divs/2/div-container.md), [galleries](https://divkit.tech/docs/en/concepts/divs/2/div-gallery.md), and [pagers](https://divkit.tech/docs/en/concepts/divs/2/div-pager.md) with a dynamic dataset. In this case, container elements aren't embedded in the layout, but are set with a [calculated expression](https://divkit.tech/docs/en/concepts/expressions.md). This is done using the [item_builder](https://divkit.tech/docs/en/concepts/divs/2/div-collection-item-builder.md) property.

## Simple example

```json translate=no
{
  "type": "container",
  "item_builder": {
    "data": [
      {
        "text": "Item 1"
      },
      {
        "text": "Item 2"
      }
    ],
    "data_element_name": "item",
    "prototypes": [
      {
        "div": {
          "type": "text",
          "text": "@{item.getString('text')}"
        }
      }
    ]
  }
}
```

In this example:

* `data`: A data array that will be used to create container elements.

* `data_element_name`: The name of the variable that contains data for the current element. This variable is available only within a prototype.

   If the `data_element_name` parameter isn't specified, the name of the variable for accessing data within a prototype defaults to `it`.

* `prototypes`: A set of prototypes used to create container elements. A prototype is a layout element cloned for each data element (from the `data` array).

The layout from the example will create a container with two elements:

* The `item` variable (the [dict_variable](https://divkit.tech/docs/en/concepts/divs/2/dict_variable.md) type) inside the first element will contain the following value: `{ "text": "Item 1" }`.

* The `item` variable inside the second element will contain the following value: `{ "text": "Item 2" }`.

The result will be a container with two text elements:

```translate=no
Item 1
Item 2
```

## Dynamic dataset

Let's complicate the example: instead of embedding data into the container description, we'll use a [variable](https://divkit.tech/docs/en/concepts/variables.md).

```json translate=no
{
  "type": "container",
  "item_builder": {
    "data": "@{items}",
    "data_element_name": "item",
    "prototypes": [
      {
        "div": {
          "type": "text",
          "text": "@{item.getString('text')}"
        }
      }
    ]
  }
}
```

For example, the `items` variable is declared in the card itself and contains the same values as the `data` property from the first example:

```json translate=no
{
  "name": "items",
  "type": "array",
  "value": [
    {
      "text": "Item 1"
    },
    {
      "text": "Item 2"
    }
  ]
}
```

With this approach, you can dynamically change the values of the `items` variable to modify the container's contents. To work with array variables, use the following actions:
- [array_insert_value](https://divkit.tech/docs/en/concepts/divs/2/div-action-array-insert-value.md)
- [array_remove_value](https://divkit.tech/docs/en/concepts/divs/2/div-action-array-remove-value.md)
- [array_set_value](https://divkit.tech/docs/en/concepts/divs/2/div-action-array-set-value.md)

## Heterogeneous data

A container can contain elements with different layout, such as images and text blocks. You can also implement this using prototypes:

```json translate=no
{
  "type": "container",
  "item_builder": {
    "data": [
      {
        "type": "text",
        "text": "Item 1"
      },
      {
        "type": "text",
        "text": "Item 2"
      },
      {
        "type": "image",
        "url": "https://image.url"
      }
    ],
    "data_element_name": "item",
    "prototypes": [
      {
        "selector": "@{item.getString('type') == 'text'}",
        "div": {
          "type": "text",
          "text": "@{item.getString('text')}"
        }
      },
      {
        "selector": "@{item.getString('type') == 'image'}",
        "div": {
          "type": "image",
          "image_url": "@{item.getUrl('url')}"
        }
      }
    ]
  }
}
```

Two prototypes are set in the `prototypes` property. Data elements are matched to the appropriate prototypes with the `selector` property. In `selector`, you can write an expression that returns a boolean value. It indicates whether the prototype is suitable for the current data element. If multiple prototypes meet the condition, the first matching prototype is used.

## Using variables in prototypes

Inside each prototype, you have access to:

1. The current data element through the variable specified in `data_element_name` (or `it` if not specified)
2. The current element's index through the `index` variable

These variables are automatically available in the prototype's scope and can be used in expressions. For example, you can use `@{item.getString('name')}` to access a field from the current data element, or `@{index}` to get the current item's position in the array.

<!-- source: en/_includes/index/troubleshooting.md -->
## Learn more {#troubleshooting}

You can discuss topics of interest in the DivKit user community in Telegram: [https://t.me/divkit_community_en](https://t.me/divkit_community_en).



[DivKit Repository](https://github.com/divkit/divkit)
<!-- endsource: en/_includes/index/troubleshooting.md -->