Actions with elements

When the user taps an element, an action is triggered.

{
  "actions": [{
    "log_id": "<unique_id>",
    "url": "div-action://<action_description>?other/parameters"
  }]
}

Parameter

Description

url

The link opened when the action is triggered: a regular URL or a DivKit action in the div-action:// format.

log_id

Optional logging ID. It must be unique within a single card.

typed

Typed action. To learn more, see Typed actions.

is_enabled

Enables or disables the action. A disabled action does not react to its event. The default value is true.

payload

Additional parameters passed to the host application.

scope_id

ID of the element whose scope the action uses when changing variable values.

menu_items

Context menu.

log_url

URL for logging.

referer

Referer URL for logging. Supported on Android and iOS.

download_callbacks

Actions performed after loading more data.

target

The tab in which the URL opens: _self or _blank. Supported on Web only.

Note

Older versions of DivKit clients ignore actions without log_id. If such clients also receive the card, pass log_id in every action.

Example: action without log_id
{
  "actions": [
    {
      "url": "div-action://set_variable?name=counter&value=1"
    }
  ]
}

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.

Note

Menu items with is_enabled: false or without active actions are not displayed in the menu. Only menu items that have at least one enabled action are displayed.

Actions can be bound to different types of gestures:

  • actions - triggered by a regular tap
  • longtap_actions - triggered by a long press
  • doubletap_actions - triggered by a double tap
  • press_start_actions - triggered at the start of a press (for example, when pressing a slider thumb)
  • press_end_actions - triggered at the end of a press (for example, when releasing a slider thumb)
  • hover_start_actions and hover_end_actions — triggered when the pointer moves over the element and when it leaves the element. They work on platforms with pointing devices (such as a mouse or stylus)

Note

When tapping on a child element with actions, container actions are not triggered. Child element actions have priority over container actions.

The capture_focus_on_action property defines what happens to the focus when an action of the element is triggered: if true, the focus moves to that element; if false, it stays on the currently focused element. The default value is true.

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-animator-start

Starts the specified animator.

div-action-animator-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. For text input fields, when called again on an already focused field, the cursor moves to the end of the text.

div-action-clear-focus

Removes focus from an element.

div-action-set-cursor-position

Sets cursor position in an input field.

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. Supports the duration parameter to control the animation duration.

div-action-scroll-to

Scrolls to a position or switches an element in a container to the specified destination value. Supports item_id destination for scrolling to an element by its identifier (Android and web) and the duration parameter to control the animation duration.

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-update-structure

Sets values in a variable of type array or dictionary with different nesting.

div-action-video

Controls video playback.

div-action-custom

Executes a custom action with user data.

div-action-haptic

Triggers haptic feedback on Android and iOS devices.

div-action-extension-action

Sends a command to an element extension. See Lottie commands.

Haptic feedback

The haptic action triggers haptic feedback (vibration) on the user's device. It is supported on Android (Views and Compose) and iOS.

Example: haptic feedback
{
  "log_id": "haptic_feedback",
  "typed": {
    "type": "haptic",
    "feedback": "success"
  }
}

Parameter

Description

type

Action type. Must be "haptic".

feedback

Type of haptic feedback. Optional parameter, defaults to "light". Possible values:
- "light" — light feedback;
- "medium" — medium feedback;
- "heavy" — heavy feedback;
- "success" — success feedback;
- "error" — error feedback.

Note

Haptic feedback depends on the device's hardware capabilities and system settings. If haptic feedback is disabled in the operating system settings or unavailable on the device, the action will be skipped without interrupting the action chain execution.

Custom actions

Custom actions allow you to execute custom logic that is not covered by standard DivKit actions. They pass arbitrary data (payload) to the host application for processing.

Using custom actions

To create a custom action, specify the type "custom" and pass the required data in the payload field:

"actions": [
  {
    "log_id": "custom_action_1",
    "typed": {
      "type": "custom"
    },
    "payload": {
      "action_type": "open_profile",
      "user_id": "12345",
      "additional_data": "custom_value"
    }
  }
]

Handling custom actions in iOS

To handle custom actions in an iOS application, you need to:

  1. Implement the DivCustomActionHandling protocol:
class MyCustomActionHandler: DivCustomActionHandling {
  func handle(
    payload: DivDictionary,
    context: DivActionHandlingContext,
    sender: AnyObject?
  ) {
    // Handle custom action
    if let actionType = payload["action_type"] as? String {
      switch actionType {
      case "open_profile":
        if let userId = payload["user_id"] as? String {
          // Open user profile
          openUserProfile(userId: userId)
        }
      default:
        break
      }
    }
  }
}
  1. Pass the handler to the DivKit configuration:
let divKitComponents = DivKitComponents(
  customActionHandler: MyCustomActionHandler(),
  // ... other parameters
)

Handling custom actions in Android

Override the handleCustomTypedAction method in your DivActionHandler and pass the handler to DivConfiguration:

class MyActionHandler : DivActionHandler() {
    override fun handleCustomTypedAction(
        action: DivActionTyped,
        scopeId: String?,
        view: DivViewFacade,
        actionUid: String?,
        reason: String?,
        evaluatedPayload: DictEvaluator?
    ) {
        // Handle the custom action
    }
}

val configuration = DivConfiguration.Builder(imageLoader)
    .actionHandler(MyActionHandler())
    .build()

The evaluatedPayload parameter contains the action payload with all expressions evaluated. If the action has no payload, the parameter is null.

Handling custom actions in Web

Pass the onCustomAction handler to the render function. It is called for actions with "typed": {"type": "custom"} and for URLs with a non-standard scheme:

render({
    id: 'smth',
    target: document.querySelector('#root'),
    json: {
        card: {},
        templates: {}
    },
    onCustomAction(action) {
        // Handle the custom action; its data is in action.payload
    }
});

Custom action parameters

Parameter

Description

payload

An arbitrary dictionary of data that is passed to the host application for processing. Can contain any custom fields.

Tip

Custom actions are useful for implementing specific business logic that is not included in the standard set of DivKit actions, such as navigation between application screens, calling specific APIs, or integration with native modules.

Order of evaluation of expressions in actions

The is_enabled and action parameter expressions are evaluated immediately before each action is executed.

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

If the counter variable is initially 0, but the first action sets the counter value to 5, then the second action will be executed because its is_enabled is checked after the first action is executed.

More things actions can do

Sets of states

Switching the appearance of content in the state element and the set_state action are described in Sets of states.

Visibility actions

Actions that are triggered without a tap, when an element appears on the screen or disappears from it, are described in Visibility actions.

Loading more data

The download action and the patch format are described in Loading more data and patches.

Collection navigation and scrolling

Switching elements and scrolling in gallery, pager, and tabs are described in Collection navigation and scrolling.

Controlling elements and data

Actions that control a particular element or data are described on the pages of those elements:

Learn more

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

DivKit Repository