Templates

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.

Without a template

{
  "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!"
          }
        ]
      }
    }
  }
}

With a template

{
  "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!"
      }
    }
  }
}

Examples

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

{
  "templates": {
    "gallery_item": "container",
    <...>
    "items": [
      {
        "type": "image",
        "$image_url": "item_image_url"
      }
    ]
  }
}

Usage example

{
  "type": "gallery",
  <...>
  "items": [
    {
      "type": "gallery_item",
      "item_image_url": "https://<...>"
    }
  ]
}

Usage features

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.

Example

{
  "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"
        }
      }
    ]
  }
}

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).

Warning

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

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.

Learn more

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

DivKit Repository

Was the article helpful?

Actions with elements

Variables