CupertinoScrollbar class Null safety

An iOS style scrollbar.

To add a scrollbar to a ScrollView, simply wrap the scroll view widget in a CupertinoScrollbar widget.

A scrollbar thumb indicates which portion of a ScrollView is actually visible.

By default, the thumb will fade in and out as the child scroll view scrolls. When isAlwaysShown is true, the scrollbar thumb will remain visible without the fade animation. This requires that the ScrollController associated with the Scrollable widget is provided to controller, or that the PrimaryScrollController is being used by that Scrollable widget.

If the scrollbar is wrapped around multiple ScrollViews, it only responds to the nearest ScrollView and shows the corresponding scrollbar thumb by default. The notificationPredicate allows the ability to customize which ScrollNotifications the Scrollbar should listen to.

If the child ScrollView is infinitely long, the RawScrollbar will not be painted. In this case, the scrollbar cannot accurately represent the relative location of the visible area, or calculate the accurate delta to apply when dragging on the thumb or tapping on the track.

Interaction

Scrollbars are interactive and can use the PrimaryScrollController if a controller is not set. Interactive Scrollbar thumbs can be dragged along the main axis of the ScrollView to change the ScrollPosition. Tapping along the track exclusive of the thumb will trigger a ScrollIncrementType.page based on the relative position to the thumb.

When using the PrimaryScrollController, it must not be attached to more than one ScrollPosition. ScrollViews that have not been provided a ScrollController and have a ScrollView.scrollDirection of Axis.vertical will automatically attach their ScrollPosition to the PrimaryScrollController. Provide a unique ScrollController to each Scrollable in this case to prevent having multiple ScrollPositions attached to the PrimaryScrollController.

This sample shows an app with two scrollables in the same route. Since by default, there is one PrimaryScrollController per route, and they both have a scroll direction of Axis.vertical, they would both try to attach to that controller. The Scrollbar cannot support multiple positions attached to the same controller, so one ListView, and its Scrollbar have been provided a unique ScrollController.

Alternatively, a new PrimaryScrollController could be created above one of the ListViews.

To create a local project with this code sample, run:
flutter create --sample=material.RawScrollbar.1 mysample

Alternatively, a new PrimaryScrollController could be created above one of the ListViews.

final ScrollController _firstController = ScrollController();

@override
Widget build(BuildContext context) {
  return LayoutBuilder(
      builder: (BuildContext context, BoxConstraints constraints) {
        return Row(
          children: <Widget>[
            SizedBox(
                width: constraints.maxWidth / 2,
                // Only one scroll position can be attached to the
                // PrimaryScrollController if using Scrollbars. Providing a
                // unique scroll controller to this scroll view prevents it
                // from attaching to the PrimaryScrollController.
                child: Scrollbar(
                  isAlwaysShown: true,
                  controller: _firstController,
                  child: ListView.builder(
                      controller: _firstController,
                      itemCount: 100,
                      itemBuilder: (BuildContext context, int index) {
                        return Padding(
                          padding: const EdgeInsets.all(8.0),
                          child: Text('Scrollable 1 : Index $index'),
                        );
                      }
                  ),
                )
            ),
            SizedBox(
                width: constraints.maxWidth / 2,
                // This vertical scroll view has not been provided a
                // ScrollController, so it is using the
                // PrimaryScrollController.
                child: Scrollbar(
                  isAlwaysShown: true,
                  child: ListView.builder(
                      itemCount: 100,
                      itemBuilder: (BuildContext context, int index) {
                        return Container(
                            height: 50,
                            color: index.isEven ? Colors.amberAccent : Colors.blueAccent,
                            child: Padding(
                              padding: const EdgeInsets.all(8.0),
                              child: Text('Scrollable 2 : Index $index'),
                            )
                        );
                      }
                  ),
                )
            ),
          ],
        );
      }
  );
}

Automatic Scrollbars on Desktop Platforms

Scrollbars are added to most Scrollable widgets by default on TargetPlatformVariant.desktop platforms. This is done through ScrollBehavior.buildScrollbar as part of an app's ScrollConfiguration. Scrollables that do not use the PrimaryScrollController or have a ScrollController provided to them will receive a unique ScrollController for use with the Scrollbar. In this case, only one Scrollable can be using the PrimaryScrollController, unless interactive is false. To prevent Axis.vertical Scrollables from using the PrimaryScrollController, set ScrollView.primary to false. Scrollable widgets that do not have automatically applied Scrollbars include

When dragging a CupertinoScrollbar thumb, the thickness and radius will animate from thickness and radius to thicknessWhileDragging and radiusWhileDragging, respectively.

This sample shows a CupertinoScrollbar that fades in and out of view as scrolling occurs. The scrollbar will fade into view as the user scrolls, and fade out when scrolling stops. The thickness of the scrollbar will animate from 6 pixels to the thicknessWhileDragging of 10 when it is dragged by the user. The radius of the scrollbar thumb corners will animate from 34 to the radiusWhileDragging of 0 when the scrollbar is being dragged by the user.

To create a local project with this code sample, run:
flutter create --sample=cupertino.CupertinoScrollbar.1 mysample

import 'package:flutter/cupertino.dart';

// ...

@override
Widget build(BuildContext context) {
  return CupertinoScrollbar(
    thickness: 6.0,
    thicknessWhileDragging: 10.0,
    radius: const Radius.circular(34.0),
    radiusWhileDragging: Radius.zero,
    child: ListView.builder(
      itemCount: 120,
      itemBuilder: (BuildContext context, int index) {
        return Center(
          child: Text('item $index'),
        );
      },
    ),
  );
}

When isAlwaysShown is true, the scrollbar thumb will remain visible without the fade animation. This requires that a ScrollController is provided to controller, or that the PrimaryScrollController is available.

To create a local project with this code sample, run:
flutter create --sample=cupertino.CupertinoScrollbar.2 mysample

import 'package:flutter/cupertino.dart';

// ...

final ScrollController _controllerOne = ScrollController();

@override
Widget build(BuildContext context) {
  return CupertinoScrollbar(
    thickness: 6.0,
    thicknessWhileDragging: 10.0,
    radius: const Radius.circular(34.0),
    radiusWhileDragging: Radius.zero,
    controller: _controllerOne,
    isAlwaysShown: true,
    child: ListView.builder(
      controller: _controllerOne,
      itemCount: 120,
      itemBuilder: (BuildContext context, int index) {
        return Center(
          child: Text('item $index'),
        );
      },
    ),
  );
}

Constructors

CupertinoScrollbar({Key? key, required Widget child, ScrollController? controller, bool isAlwaysShown = false, double thickness = defaultThickness, double thicknessWhileDragging, Radius radius = defaultRadius, Radius radiusWhileDragging, ScrollNotificationPredicate? notificationPredicate, ScrollbarOrientation? scrollbarOrientation}): Creates an iOS style scrollbar that wraps the given child. [...]
const

Properties

child → Widget: The widget below this widget in the tree. [...]
final, inherited
controller → ScrollController?: The ScrollController used to implement Scrollbar dragging. [...]
final, inherited
crossAxisMargin → double: Distance from the scrollbar thumb side to the nearest cross axis edge in logical pixels. [...]
final, inherited
fadeDuration → Duration: The Duration of the fade animation. [...]
final, inherited
hashCode → int: The hash code for this object. [...]
@nonVirtual, read-only, inherited
interactive → bool?: Whether the Scrollbar should be interactive and respond to dragging on the thumb, or tapping in the track area. [...]
final, inherited
isAlwaysShown → bool?: Indicates that the scrollbar should be visible, even when a scroll is not underway. [...]
final, inherited
key → Key?: Controls how one widget replaces another widget in the tree. [...]
final, inherited
mainAxisMargin → double: Distance from the scrollbar's start and end to the edge of the viewport in logical pixels. It affects the amount of available paint area. [...]
final, inherited
minOverscrollLength → double?: The preferred smallest size the scrollbar thumb can shrink to when viewport is overscrolled. [...]
final, inherited
minThumbLength → double: The preferred smallest size the scrollbar thumb can shrink to when the total scrollable extent is large, the current visible viewport is small, and the viewport is not overscrolled. [...]
final, inherited
notificationPredicate → ScrollNotificationPredicate: A check that specifies whether a ScrollNotification should be handled by this widget. [...]
final, inherited
pressDuration → Duration: The Duration of time that a LongPress will trigger the drag gesture of the scrollbar thumb. [...]
final, inherited
radius → Radius?: The Radius of the scrollbar thumb's rounded rectangle corners. [...]
final, inherited
radiusWhileDragging → Radius: The radius of the scrollbar edges when the scrollbar is being dragged by the user. [...]
final
runtimeType → Type: A representation of the runtime type of the object.
read-only, inherited
scrollbarOrientation → ScrollbarOrientation?: Dictates the orientation of the scrollbar. [...]
final, inherited
thickness → double?: The thickness of the scrollbar in the cross axis of the scrollable. [...]
final, inherited
thicknessWhileDragging → double: The thickness of the scrollbar when it's being dragged by the user. [...]
final
thumbColor → Color?: The color of the scrollbar thumb. [...]
final, inherited
timeToFade → Duration: The Duration of time until the fade animation begins. [...]
final, inherited

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree. [...]
inherited
createState() → RawScrollbarState<CupertinoScrollbar>: Creates the mutable state for this widget at a given location in the tree. [...]
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children. [...]
@protected, inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node. [...]
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a non-existent method or property is accessed. [...]
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep. [...]
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object. [...]
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a string representation of this node and its descendants. [...]
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object. [...]
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator. [...]
@nonVirtual, inherited

Constants

defaultRadius → const Radius: Default value for radius if it's not specified in CupertinoScrollbar.
Radius.circular(1.5)
defaultRadiusWhileDragging → const Radius: Default value for radiusWhileDragging if it's not specified in CupertinoScrollbar.
Radius.circular(4.0)
defaultThickness → const double: Default value for thickness if it's not specified in CupertinoScrollbar.
3
defaultThicknessWhileDragging → const double: Default value for thicknessWhileDragging if it's not specified in CupertinoScrollbar.
8.0