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

# Templates

## Description {#description}

Templates are required to get rid of code duplication and not to describe each card from scratch. When using a template, you can specify and override all fields of the parent element.

If you often create cards with the same or similar content, save them as templates.

Templates help you:

- Spend less time creating cards.

- Reduce the size of incoming JSON.
- Reduce the number of possible errors and typos when creating cards.



{% cut "Without a template" %}


```json translate=no
{
  "states": {
    "state1": {
      "data": {
        "type": "container",
        "direction": "vertical",
        "paddings": {
          "left": 4,
          "top": 4,
          "right": 4,
          "bottom": 4
        },
        "items": [
          {
            "type": "image",
            "width": {
              "type": "fixed",
              "value": "40",
              "unit": "dp"
            },
            "height": {
              "type": "fixed",
              "value": "40",
              "unit": "dp"
            },
            "image_url": "https://image.storage.net/icon.png"
          },
          {
            "type": "text",
            "font_size": 16,
            "text": "Hello, World!"
          }
        ]
      }
    }
  }
}
```


{% endcut %}

{% cut "With a template" %}


```json translate=no
{
  "templates": {
    "image-with-text": {
      "type": "container",
      "direction": "vertical",
      "paddings": {
        "left": 4,
        "top": 4,
        "right": 4,
        "bottom": 4
      },
      "items": [
        {
          "type": "image",
          "width": {
            "type": "fixed",
            "value": "40",
            "unit": "dp"
          },
          "height": {
            "type": "fixed",
            "value": "40",
            "unit": "dp"
          },
          "$image_url": "icon_url"
        },
        {
          "type": "text",
          "font_size": 16,
          "$text": "title_text"
        }
      ]
    }
  },
  "states": {
    "state1": {
      "data": {
        "type": "image-with-text",
        "icon_url": "https://image.storage.net/icon.png",
        "title_text": "Hello, World!"
      }
    }
  }
}
```


{% endcut %}



## Examples {#example}

Templates can be used in complex elements (for example, in a container with child elements). To change the fields of the child elements, they need to be renamed in the parameters: `$field_name_in_element: new_field_name`

Edit the `gallery_item` element type with the `item_image_url` field.

**Renaming example**

```json translate=no
{
  "templates": {
    "gallery_item": "container",
    <...>
    "items": [
      {
        "type": "image",
        "$image_url": "item_image_url"
      }
    ]
  }
}
```

**Usage example**

```json translate=no
{
  "type": "gallery",
  <...>
  "items": [
    {
      "type": "gallery_item",
      "item_image_url": "https://<...>"
    }
  ]
}
```


## Usage features {#restiriction}

Templates can be inherited from each other. They are subject to the same rules as when creating a regular template.

### Parameter resolution in template chains

When resolving parameters in a template chain, platform behavior differs: on **Android and iOS** a property value propagates down through the entire chain of nested templates, while on **Web** each template receives only the value passed by its direct caller.

{% cut "Example" %}

```json translate=no
{
  "templates": {
    "root": {
      "type": "container",
      "items": [
        {
          "type": "parent",
          "textRef": "parent text"
        }
      ]
    },
    "parent": {
      "type": "container",
      "items": [
        {
          "type": "child",
          "textRef": "Child text"
        }
      ]
    },
    "child": {
      "type": "text",
      "$text": "textRef"
    }
  },
  "card": {
    "log_id": "test",
    "states": [
      {
        "state_id": 0,
        "div": {
          "type": "root",
          "textRef": "Root text"
        }
      }
    ]
  }
}
```

{% endcut %}

In this example, `child` receives `textRef` from three levels: `"Root text"` (from card), `"parent text"` (from `root` template), `"Child text"` (from `parent` template).

- **iOS and Android:** `"Root text"` is displayed — the value from the card propagates down through the entire chain.
- **Web:** `"Child text"` is displayed — the template uses the value from its direct caller (`parent`).

{% note warning %}

Avoid passing the same parameter at multiple levels of a template chain — behavior is platform-dependent and may be unpredictable.

{% endnote %}

Template restrictions:

- You can't use system names in template and variable names. For example, you can't create a `container` template or a `text` field.
- You can create templates of only basic visual elements.
- The template must have a `type` field.

<!-- 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 -->