ScrollableControl

Shared scroll behavior for controls that expose a scrollable viewport.

This mixin-style control is inherited by controls such as Column, Row, ResponsiveRow, View, ListView, and GridView. It provides a common API for:

• enabling/disabling scrolling and scrollbar visibility via scroll;
• receiving throttled scroll notifications via on_scroll and scroll_interval;
• imperatively changing position with scroll_to.

Inherits: Control

Properties

• auto_scroll - Whether the scrollbar should automatically move its position to the end when children updated.
• scroll - Defines the scroll bar configuration of this control.
• scroll_interval - Throttling in milliseconds for on_scroll event.

Events

• on_scroll - Called when scroll position is changed by a user.

Methods

• scroll_to - Moves the scroll position.

Properties

buildauto_scrollclass-attributeinstance-attribute

auto_scroll: bool = False

Whether the scrollbar should automatically move its position to the end when children updated.

Note

Must be False for scroll_to method to work.

buildscrollclass-attributeinstance-attribute

scroll: ScrollMode | Scrollbar | None = None

Defines the scroll bar configuration of this control.

Can be a Scrollbar instance for full control over the appearance of the scrollbar, or a ScrollMode value, for ready-made scrollbar behaviors.

buildscroll_intervalclass-attributeinstance-attribute

scroll_interval: Number = 10

Throttling in milliseconds for on_scroll event.

Events

bolton_scrollclass-attributeinstance-attribute

on_scroll: EventHandler[OnScrollEvent] | None = None

Called when scroll position is changed by a user.

Methods

deployed_codescroll_toasync

scroll_to(
    offset: float | None = None,
    delta: float | None = None,
    scroll_key: ScrollKey
    | str
    | int
    | float
    | bool
    | None = None,
    duration: DurationValue = 0,
    curve: AnimationCurve = AnimationCurve.EASE,
)

Moves the scroll position.

Parameters:

• offset (float | None, default: None) - Absolute scroll target in pixels. A negative value is interpreted relative to the end (e.g. -1 to jump to the very end).
• delta (float | None, default: None) - Relative scroll change in pixels. Positive values scroll forward, negative values scroll backward.
• scroll_key (ScrollKey | str | int | float | bool | None, default: None) - Key of the target control to scroll to.
• duration (DurationValue, default: 0) - The scroll animation duration.
• curve (AnimationCurve, default: AnimationCurve.EASE) - The scroll animation curve.

Notes

• Exactly one of offset, delta or scroll_key should be provided.
• auto_scroll must be False.
• This method is ineffective for controls (e.g. ListView, GridView) that build items dynamically.