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 |
|
|
The link opened when the action is triggered: a regular URL or a DivKit action in the |
|
|
Optional logging ID. It must be unique within a single card. |
|
|
Typed action. To learn more, see Typed actions. |
|
|
Enables or disables the action. A disabled action does not react to its event. The default value is |
|
|
Additional parameters passed to the host application. |
|
|
ID of the element whose scope the action uses when changing variable values. |
|
|
Context menu. |
|
|
URL for logging. |
|
|
Referer URL for logging. Supported on Android and iOS. |
|
|
Actions performed after loading more data. |
|
|
The tab in which the URL opens: |
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 taplongtap_actions- triggered by a long pressdoubletap_actions- triggered by a double tappress_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_actionsandhover_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 |
|
|
Tip
We recommend using typed actions. They allow you to avoid encoding parameters and simplify visual perception and layout validation.
|
Name |
Description |
|
Starts the specified animator. |
|
|
Stops the specified animator. |
|
|
Adds a value to an array. |
|
|
Removes a value from an array. |
|
|
Sets a value in an array by index. |
|
|
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. |
|
|
Removes focus from an element. |
|
|
Sets cursor position in an input field. |
|
|
Copies data to the clipboard. |
|
|
Sets a value in a dictionary by key. |
|
|
Downloads additional data in |
|
|
Shows a tooltip. |
|
|
Hides a tooltip. |
|
|
Scrolls a scrollable container from the current position by the specified |
|
|
Scrolls to a position or switches an element in a container to the specified |
|
|
Sets a new appearance for content in |
|
|
Temporarily stores a variable in storage. |
|
|
Assigns a value to a variable. |
|
|
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. |
|
|
Controls a timer. |
|
|
Sets values in a variable of type array or dictionary with different nesting. |
|
|
Controls video playback. |
|
|
Executes a custom action with user data. |
|
|
Triggers haptic feedback on Android and iOS devices. |
|
|
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 |
|
|
Action type. Must be |
|
|
Type of haptic feedback. Optional parameter, defaults to |
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:
- Implement the
DivCustomActionHandlingprotocol:
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
}
}
}
}
- 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 |
|
|
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:
- Cursor position in an input field: Input field.
- Showing and hiding tooltips: Tooltips.
- Video playback: Video.
- Starting and stopping timers: Timers.
- Changing variable values: Variables.
- Keeping values between sessions: Stored values.
Learn more
You can discuss topics of interest in the DivKit user community in Telegram: https://t.me/divkit_community_en.