Actions with elements

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

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

Typed actions

Typed actions differ from standard actions in format. They can be specified in a JSON object. In standard actions, all parameters must be specified in the url field.

Action example

Typed action example

"actions": [
  {
    "log_id": "set_2",
    "url": "div-action://set_variable?name=variable&value=123"
  }
]
"actions": [
  {
    "log_id": "set_2",
    "typed": {
      "type": "set_variable",
      "variable_name": "variable",
      "value": {
        "type": "integer",
        "value": 123
      }
    }
  }
]

Tip

We recommend using typed actions. They allow you to avoid encoding parameters and simplify visual perception and layout validation.

Name

Description

div-action-animation-start

Starts the specified animator.

div-action-animation-stop

Stops the specified animator.

div-action-array-insert-value

Adds a value to an array.

div-action-array-remove-value

Removes a value from an array.

div-action-array-set-value

Sets a value in an array by index.

div-action-focus-element

Requests focus for an element.

div-action-clear-focus

Removes focus from an element.

div-action-copy-to-clipboard

Copies data to the clipboard.

div-action-dict-set-value

Sets a value in a dictionary by key.

div-action-download

Downloads additional data in div-patch format and updates the current element.

div-action-show-tooltip

Shows a tooltip.

div-action-hide-tooltip

Hides a tooltip.

div-action-scroll-by

Scrolls a scrollable container from the current position by the specified item_count or offset value.

div-action-scroll-to

Scrolls to a position or switches an element in a container to the specified destination value.

div-action-set-state

Sets a new appearance for content in div-state.

div-action-set-stored-value

Temporarily stores a variable in storage.

div-action-set-variable

Assigns a value to a variable.

div-action-submit

Sends variables from a container via a link. Data sending configuration can be determined by the host application. By default, variables are passed in the request body as JSON, request method is POST.

div-action-timer

Controls a timer.

div-action-video

Controls video playback.

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>

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 the state will revert to the original one when the element is re-created (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 in order to switch:

div-action://set_state?state_id=[root state id]/[element's div_id]/[state's state_id]
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"
    }
  ]
}

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>

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

Note

To use patches on Android, pass a DivDownloader implementation to your DivConfiguration.

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>

Parameter

Description

id

ID of the element in which the current one must be switched.

item

Index of the element to scroll to.

overflow

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

  • clamp: Stop switching at the boundary element (default value).
  • ring: Switch to the start or end depending on the current element.

To jump to the start or end of the gallery, specify the following action:

div-action://scroll_to_start?id=<div_id>
div-action://scroll_to_end?id=<div_id>

Parameter

Description

id

ID of the element in which the current one must be switched.

If the elements inside gallery are bigger than the gallery itself, the scroll_to_end action scrolls it to the end of the last element.

To scroll the gallery forward or backward, specify the following action:

div-action://scroll_forward?id=<div_id>&step=<dp_count>&overflow=<clamp|ring>
div-action://scroll_backward?id=<div_id>&step=<dp_count>&overflow=<clamp|ring>

To scroll the gallery to a specific value, specify the following action:

div-action://scroll_to_position?id=<div_id>&step=<dp_count>

Parameter

Description

id

ID of the element in which the current one must be switched.

step

Value in dp representing either the position to scroll the gallery to or the scroll step, depending on the action.

overflow

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

  • clamp: Stop switching at the boundary element (default value).
  • ring: Switch to the start or 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>

Parameter

Description

id

Tooltip ID.

Video controls

To control a video, use the video action:

div-action://video?id=video_id&action=<start|pause>

Parameter

Description

id

ID of an element with a video.

action

Actions with videos:

  • start: Resume playback.
  • pause: Pause.

Timer controls

To control a timer, use the timer action:

div-action://timer?action=<action>&id=<id>

Parameter

Description

id

Timer ID.

action

Actions with timers:

  • start: Start the timer.
  • stop: Stop the timer.
  • pause: Pause the timer.
  • resume: Resume the timer.
  • cancel: Interrupt the timer.
  • reset: Reset the timer.

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>

Parameter

Description

name

Variable name.

value

New value.

Saving variables to temporary storage

To temporarily store variable values, specify the set_stored_value action:

div-action://set_stored_value?name=<variable_name>&value=<new_value>&type=<variable_type>&lifetime=<lifetime_in_sec>

Parameter

Description

name

Variable name.

value

Value to save.

type

Variable type. Must be string, number, integer, url, or color.

lifetime

Variable's storage lifetime in seconds. If you attempt to retrieve the variable after this time, it will be considered expired.

To get the value of a stored variable, use calculated expressions:

@{getStoredStringValue(name, default)}
@{getStoredNumberValue(name, default)}
@{getStoredIntegerValue(name, default)}
@{getStoredUrlValue(name, default)}
@{getStoredColorValue(name, default)}

The name parameter still represents the name of the stored variable, and default is the value to return if the variable can't be found or has expired.

Order of evaluation of expressions in actions

When multiple actions are specified in an array, there are two types of expressions with different evaluation timing:

  1. is_enabled expressions - All is_enabled expressions for all actions in the array are evaluated at once before any actions are executed
  2. Action parameter expressions - Each action's parameter expressions are evaluated just before that action is executed

This ensures that changes made by previous actions in the sequence are properly reflected in subsequent action parameters.

For example, in the following sequence of actions:

"actions": [
  {
    "log_id": "1",
    "is_enabled": "@{enable_actions}",
    "typed": {
      "type": "set_variable",
      "variable_name": "counter",
      "value": {
        "type": "integer",
        "value": 5
      }
    }
  },
  {
    "log_id": "2",
    "is_enabled": "@{counter > 0}",
    "typed": {
      "type": "set_variable",
      "variable_name": "message",
      "value": {
        "type": "string",
        "value": "Done"
      }
    }
  },
  {
    "log_id": "3",
    "is_enabled": "@{message != ''}",
    "typed": {
      "type": "set_variable",
      "variable_name": "result",
      "value": {
        "type": "string",
        "value": "@{message}"
      }
    }
  }
]
  • All is_enabled expressions (@{enable_actions}, @{counter > 0}, @{message != ''}) are evaluated simultaneously at the very beginning, before executing any actions
  • The expression @{message} in the third action is evaluated just before executing the third action and will reflect the changes made by the second action

This means that if the counter variable is initially 0, then the is_enabled expressions for the second and third actions will be evaluated as false even before the first action is executed, even though the first action should have set the counter value to 5.

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

Previous