ListView

A scrollable list of controls, optimized for many items. Prefer it over a scrolling column when the list is long.

Example

list_view(
  expand: true,
  spacing: 4,
  padding: 8,
  children: messages.map { |m| list_tile(title: text(m.subject), subtitle: text(m.preview)) }
)

Common properties

• children — the list items
• horizontal — scroll horizontally instead of vertically
• spacing
• padding
• item_extent — fixed item size for faster layout
• divider_thickness — draw dividers between items
• auto_scroll — keep the latest item in view (chat/logs)
• reverse
• cache_extent

Usage

list_view expands to fill its parent — give it expand: true inside a column, or a fixed height. For huge or streamed lists, set build_controls_on_demand: true.

Complete API

Helpers

• list_view(children = ..., **props)
• listview(children = ..., **props)

Accepted properties

• adaptive — Adapts to the platform (Material/Cupertino) when true.
• align — Alignment of the control within its parent.
• animate_align — Animates alignment changes.
• animate_margin — Animates margin changes.
• animate_offset — Animates offset changes.
• animate_opacity — Animates opacity changes.
• animate_position — Animates position changes.
• animate_rotation — Animates rotation changes.
• animate_scale — Animates scale changes.
• animate_size — Animates size changes.
• aspect_ratio — Width-to-height ratio to maintain.
• auto_scroll — Sets the auto scroll property.
• badge — Badge drawn on the corner of the control.
• bottom — Bottom offset when positioned inside a stack.
• build_controls_on_demand — Sets the build controls on demand property.
• cache_extent — Sets the cache extent property.
• clip_behavior — How content overflowing the bounds is clipped.
• col — Responsive column span (1-12) per breakpoint.
• controls — The list of child controls.
• data — Arbitrary value you can attach to the control and read back in handlers.
• disabled — Disables interaction when true.
• divider_thickness — Sets the divider thickness property.
• expand — Fills the available space along the parent's main axis when true.
• expand_loose — Like expand, but only grows up to the child's natural size.
• first_item_prototype — Sets the first item prototype property.
• height — Fixed height in logical pixels.
• horizontal — Sets the horizontal property.
• item_extent — Sets the item extent property.
• key — Stable identity used to preserve state across rebuilds.
• left — Left offset when positioned inside a stack.
• margin — Outer spacing around the control.
• offset — Translation offset applied to the control.
• opacity — Opacity from 0.0 (transparent) to 1.0 (opaque).
• padding — Inner spacing between the border and the content.
• prototype_item — Sets the prototype item property.
• reverse — Sets the reverse property.
• right — Right offset when positioned inside a stack.
• rotate — Rotation applied to the control.
• rtl — Renders right-to-left when true.
• scale — Scale transform applied to the control.
• scroll — Sets the scroll property.
• scroll_interval — Sets the scroll interval property.
• semantic_child_count — Sets the semantic child count property.
• size_change_interval — Throttle interval for on_size_change, in ms.
• spacing — Sets the spacing property.
• tooltip — Text shown on hover/long-press.
• top — Top offset when positioned inside a stack.
• visible — Hides the control when false.
• width — Fixed width in logical pixels.

Events

• on_animation_end — Fired when an animation completes.
• on_scroll — Fired when the scroll position changes.
• on_size_change — Fired when the control's size changes.

Wire reference

• Family: shared
• Widget type: listview