Actions with elements

  1. Sets of states
    1. Empty state
    2. Nested states
  2. Actions when appearing
  3. Loading more data
  4. Switching elements
  5. Managing tooltips
  6. Changing the values of variables
    1. Learn more

When the user taps the card, action calls the event specified in url.

{
  "actions": [{ 
    "log_id": "<unique_id>",
    "url": "div-action://<action_description>?other/parameters"
  }]
}
Copied to clipboard
Parameter Description
url An event that is triggered by tapping the card.
log_id

Logging ID. It must be unique within a single card.

Parameter Description
url An event that is triggered by tapping the card.
log_id

Logging ID. It must be unique within a single card.

You can open the menu by tapping using the special menu_items parameter. If at least one action in the array has a menu_items field, tapping the element will show a menu, and all other fields will be ignored.

A separate type of action are actions that are triggered only by a long tap (longtap-actions).

Sets of states

The state element switches the appearance of content. You can use it to add:

  • Buttons that change their state (for example, the like icon when tapped).
  • Content that can be expanded (for example, a bridge card or a geo block).

One picture changes to another, but the user sees it as an interaction.

To switch to a different state, use url:

div-action://set_state?state_id=<div_data_state_id/div_id/state_id>&temporary=<bool>
Copied to clipboard

The path is formed from the hierarchy root:

Parameter Description
state_id

The path of the state inside state that needs to be activated. Set in div_data_state_id/div_id/state_id format.

Can be hierarchical: div_data_state_id/div_id_1/state_id_1/../div_id_n/state_id_n

Consists of:
  • div_data_state_id: state_id numeric value of the state object in data.
  • div_id: div_id value of the state object.
  • state_id: state_id value of the state object in state.
temporary

Indicates a state change:

  • true: The change is temporary and when the element is re-created, the state will change back to the initial one (default value).
  • false: The state change is permanent.
Parameter Description
state_id

The path of the state inside state that needs to be activated. Set in div_data_state_id/div_id/state_id format.

Can be hierarchical: div_data_state_id/div_id_1/state_id_1/../div_id_n/state_id_n

Consists of:
  • div_data_state_id: state_id numeric value of the state object in data.
  • div_id: div_id value of the state object.
  • state_id: state_id value of the state object in state.
temporary

Indicates a state change:

  • true: The change is temporary and when the element is re-created, the state will change back to the initial one (default value).
  • false: The state change is permanent.
View an interactive example

Empty state

If you need to hide a block, don't add a div field, but specify "state_id": "empty".

View an interactive example

Nested states

If multiple states are nested in each other, write the full path from the root to switch between them:
div-action://set_state?state_id=[root state id]/[element div_id]/[state state_id]
Copied to clipboard
View an interactive example

Actions when appearing

visibility elements are triggered when an element is shown on the screen.

{
  "visibility_actions": [
    {
      "log_id":"content_01_visibility",
      "visibility_percentage": 100,
      "visibility_duration": 1000,
      "url": "div-action://none"
    }
  ]
}
Copied to clipboard
Parameter Description
visibility_percentage Percentage of the element's visible area.
visibility_duration The minimum time of its visibility.
Parameter Description
visibility_percentage Percentage of the element's visible area.
visibility_duration The minimum time of its visibility.

Loading more data

To load more data in the form of a patch and update the current element, specify the download action:

div-action://download?url=<patch_url>
Copied to clipboard
Parameter Description
url URL to get the patch.
Parameter Description
url URL to get the patch.

Response format:

{
  "patch": {
    // data in patch format
  },
  "templates": {
    // templates that can be used in the patch section
  }
}
Copied to clipboard

Switching elements

To navigate inside gallery, pager, and tabs, specify an action:

  • set_current_item: For the current element.
  • set_next_item: For the next element.
  • set_previous_item: For the previous element.
div-action://set_current_item?id=<div_id>&item=<item_index>
div-action://set_next_item?id=<div_id>&overflow=<clamp|ring>
div-action://set_previous_item?id=<div_id>&overflow=<clamp|ring>
Copied to clipboard
Parameter Description
id ID of the element in which the current one must be switched.
item The minimum time of its visibility.
overflow

Specifies how navigation will occur when the boundary elements are reached:

  • clamp: Transition will stop at the boundary element (default value).
  • ring: Transition will be to the beginning or the end depending on the current element.
Parameter Description
id ID of the element in which the current one must be switched.
item The minimum time of its visibility.
overflow

Specifies how navigation will occur when the boundary elements are reached:

  • clamp: Transition will stop at the boundary element (default value).
  • ring: Transition will be to the beginning or the end depending on the current element.

Managing tooltips

To show or hide tooltips, specify the show_tooltip or hide_tooltip action:

div-action://show_tooltip?id=<tooltip_id>
div-action://hide_tooltip?id=<tooltip_id>
Copied to clipboard
Parameter Description
id Tooltip ID.
Parameter Description
id Tooltip ID.

Changing the values of variables

To change the value of variables, specify the set_variable action:

div-action://set_variable?name=<variable_name>&value=<new_value>
Copied to clipboard
Parameter Description
name Variable name.
value New value.
Parameter Description
name Variable name.
value New value.

Learn more

Follow DivKit news in the Telegram channel: http://t.me/divkit_news

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

DivKit Repository