Collection navigation and scrolling

The actions on this page switch the current element and control scrolling in gallery, pager, and tabs.

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.

Jump to the start or end of the gallery

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.

Scroll the gallery several dp forward or backward, or to a specific value

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.

Typed actions scroll_to and scroll_by

The same transitions can be described with the typed actions scroll_to and scroll_by. Both have the parameters id (ID of the element to scroll), animated (enables the animation, true by default), and duration.

The scroll_to action goes to the position set in the destination parameter:

Value of `type`	Description
`index`	The element with the index given in `value`.
`item_id`	The child element with the ID given in `value`. Supported on Android and Web.
`offset`	The position in dp from the container start, given in `value`. Only applies in `gallery`.
`start`	The start of the container.
`end`	The end of the container.

The scroll_by action scrolls the container from the current position by item_count elements or by offset dp (in gallery only). Negative values scroll back. The overflow parameter defines the behavior at the container boundary: clamp (default) or ring.

Scroll duration

In the scroll_to and scroll_by typed actions, duration sets the animation duration in milliseconds. It must be a non-negative integer. Without duration, the default platform animation is used; duration: 0 or animated: false makes scrolling instant.

For example, scroll to the third gallery item in 500 ms:

{
  "log_id": "scroll_to_item",
  "typed": {
    "type": "scroll_to",
    "id": "my_gallery",
    "destination": {"type": "index", "value": 2},
    "duration": 500
  }
}

To move relative to the current item, use scroll_by with item_count. For example, move one page forward without animation:

{
  "log_id": "scroll_by_instant",
  "typed": {
    "type": "scroll_by",
    "id": "my_pager",
    "item_count": 1,
    "duration": 0
  }
}

Multi-page scroll in pager

Set multi_page_scroll to true to scroll several pager pages with one swipe. The default is false. This setting does not affect programmatic scrolling. Combine it with infinite_scroll to loop through the pages.

{
  "type": "pager",
  "id": "multi_page_pager",
  "layout_mode": {
    "type": "fixed",
    "neighbour_page_width": {
      "type": "fixed",
      "value": 0
    }
  },
  "multi_page_scroll": true,
  "infinite_scroll": true,
  "items": [
    {
      "type": "text",
      "text": "Page 1"
    },
    {
      "type": "text",
      "text": "Page 2"
    },
    {
      "type": "text",
      "text": "Page 3"
    }
  ]
}

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?

Visibility actions

Loading more data and patches