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 to automatically move the scroll position to the end when the content changes.
• auto_scroll_animation - Animation used when auto_scroll moves the view to the end.
• 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 to automatically move the scroll position to the end when the content changes.

This keeps the view pinned to the end as new children are added and as existing content grows in place (e.g. text streamed into an existing child). Pinning is suspended while the user has scrolled away from the end, and resumes once they scroll back.

Note

Must be False for scroll_to method to work.

buildauto_scroll_animationclass-attributeinstance-attribute

auto_scroll_animation: AnimationValue | None = None

Animation used when auto_scroll moves the view to the end.

Accepts an Animation (duration + curve), an int duration in milliseconds, or True. Defaults to a 1 second ease animation; set a duration of 0 for an instant jump (recommended when following fast, token-by-token streaming so the view stays tightly pinned).

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.