Scrollbar

A scroll indicator drawn beside child (vertical) or below it (horizontal), reflecting a ScrollController (or a ListController via Scrollbar.list). The thumb’s size shows the visible fraction and its position shows how far you’ve scrolled; when everything fits, the thumb fills the track unless showWhenFits is false.

Learn more: Lists & scrolling

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

// The flag on ListView and ScrollView adds one and shares their controller:
ListView.builder(
  itemCount: rows.length,
  itemBuilder: (context, i, highlighted) => Text(rows[i].label),
  scrollbar: true,
)

// Or wrap a view you control, passing the controller it scrolls with:
Scrollbar(
  controller: scroll,
  child: ScrollView(controller: scroll, child: child),
)

Details

ScrollView(scrollbar: true) and ListView(scrollbar: true) add one that shares the view’s own controller. Wrap a view yourself to style the bar, giving it and the view the same controller.

When the mouse is enabled, click the track or drag the thumb to scroll — the drag is captured, so it keeps tracking even past the bar’s edge. Metrics are read at paint (after the scrollable lays out), so the thumb is correct on the first frame and follows scrolling automatically.

The bar takes its gutter from its own space, so it needs a bounded width (vertical) or height (horizontal); laid out without one, it throws a StateError.

Constructors

Scrollbar()

Parameter	Type	Default	Description
controller:	ScrollController	required	The controller of the scroll view in child; give that view the same controller. The thumb follows the controller’s extents and ScrollController.offset, and a click or drag on the bar sets that offset.
child:	Widget	required	The scrolling view the bar reflects, which must scroll with the controller the bar was given. It gets all the space except the bar’s gutter.
thickness:	int	1	How thick the bar is: the glyph columns of a vertical bar’s gutter, or the rows of a horizontal bar’s. Each column or row repeats the same track and thumb. More
scrollDirection:	Axis	Axis.vertical	Must match the axis of the owning view. Horizontal bars use a bottom gutter.
trackStyle:	CellStyle	const CellStyle(dim: true)	The style of the track, the part of the bar the thumb doesn’t cover, drawn with │ (vertical) or ─ (horizontal). Defaults to dim.
thumbStyle:	CellStyle	CellStyle.none	The style of the thumb, drawn with █. Defaults to CellStyle.none, the terminal’s own colors: the bar doesn’t read the theme.
showWhenFits:	bool	true	Whether to draw the bar when all content is visible. When false, a fitting view keeps its gutter and child identity but paints no bar and ignores track clicks and drags. The default preserves the full-track thumb.

• thickness: A bar glyph is one cell wide, or two on a terminal measured to draw ambiguous-width glyphs double-width, so a vertical gutter is thickness or twice that many cells wide.

Scrollbar.list()

Scrollbar for a ListView, including partial visibility within oversized items. Unmeasured items count equally, so geometry is approximate for mixed sizes. Dragging to either endpoint reaches the actual content edge.

Parameter	Type	Default	Description
controller:	ListController	required	The controller of the list in child; give that list the same controller. The thumb follows ListController.scrollFraction and ListController.visibleFraction, and a click or drag on the bar calls ListController.jumpToFraction, which scrolls without moving the list’s cursor.
child:	Widget	required	The scrolling view the bar reflects, which must scroll with the controller the bar was given. It gets all the space except the bar’s gutter.
thickness:	int	1	How thick the bar is: the glyph columns of a vertical bar’s gutter, or the rows of a horizontal bar’s. Each column or row repeats the same track and thumb. More
scrollDirection:	Axis	Axis.vertical	Must match the axis of the owning view. Horizontal bars use a bottom gutter.
trackStyle:	CellStyle	const CellStyle(dim: true)	The style of the track, the part of the bar the thumb doesn’t cover, drawn with │ (vertical) or ─ (horizontal). Defaults to dim.
thumbStyle:	CellStyle	CellStyle.none	The style of the thumb, drawn with █. Defaults to CellStyle.none, the terminal’s own colors: the bar doesn’t read the theme.
showWhenFits:	bool	true	Whether to draw the bar when all content is visible. When false, a fitting view keeps its gutter and child identity but paints no bar and ignores track clicks and drags. The default preserves the full-track thumb.

Source

Scrollbar is defined in packages/fleury/lib/src/widgets/scrollbar.dart.

Category: Lists & data · All widgets

Live demo

scroll_edges.dart

Restart Run Expand

Example · editable Revert Format

import 'package:fleury/fleury_core.dart';

class ScrollEdges extends StatefulWidget {
  const ScrollEdges({super.key});

  @override
  State<ScrollEdges> createState() => _ScrollEdgesState();
}

class _ScrollEdgesState extends State<ScrollEdges> {
  final scroll = ScrollController();
  EdgeBehavior edgeBehavior = EdgeBehavior.bubble;
  bool paneFocused = false;
  bool continued = false;

  @override
  void dispose() {
    scroll.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => FocusTraversalGroup(
    child: Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        const Text('Edge behavior'),
        Select<EdgeBehavior>(
          semanticLabel: 'Edge behavior',
          value: edgeBehavior,
          options: const [
            SelectOption(
              value: EdgeBehavior.bubble,
              label: 'Bubble (leave pane)',
            ),
            SelectOption(
              value: EdgeBehavior.contain,
              label: 'Contain (stay in pane)',
            ),
          ],
          onChanged: (value) =>
              setState(() => edgeBehavior = value),
        ),
        const SizedBox(height: 1),
        NotifierBuilder(
          notifier: scroll,
          builder: (context, _) {
            final first = scroll.offset + 1;
            final last =
                scroll.offset + scroll.viewportExtent;
            final edge = scroll.atStart
                ? 'TOP'
                : scroll.atEnd
                ? 'BOTTOM'
                : 'MIDDLE';
            return Text('Rows $first–$last / 8 · $edge');
          },
        ),
        Panel(
          title: 'Scroll pane',
          expandChild: false,
          focused: paneFocused,
          child: FocusDetector(
            onFocusChange: (value) =>
                setState(() => paneFocused = value),
            child:
                SizedBox(
                  height: 4,
                  child: ScrollView(
                    controller: scroll,
                    autofocus: true,
                    scrollbar: true,
                    edgeBehavior: edgeBehavior,
                    child: Column(
                      crossAxisAlignment:
                          CrossAxisAlignment.start,
                      children: [
                        const Text('1 ─── TOP'),
                        for (var n = 2; n < 8; n++)
                          Text('$n'),
                        const Text('8 ─── BOTTOM'),
                      ],
                    ),
                  ),
                ),
          ),
        ),
        Button(
          text: 'Next',
          onPressed: () => setState(() => continued = true),
        ),
        Text(
          paneFocused
              ? 'Focus: scroll pane'
              : 'Focus: controls',
        ),
        if (continued) const Text('Next selected'),
      ],
    ),
  );
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs ⛶ Expand