Skip to content
Boring Doc
BreakingHigh impactOfficial migration guidesince 2.2.0landed 2.2.0-10.0.prewindowslinux

Default Scrollbars on Desktop

Framework · Official source

What changed?

`ScrollBehavior`s now automatically apply `Scrollbar`s to scrolling widgets on desktop platforms - Mac, Windows and Linux.

Original behavior

Prior to this change, `Scrollbar`s were applied to scrolling widgets manually by the developer across all platforms. This did not match developer expectations when executing Flutter applications on desktop platforms.

New behavior

The previous approach called on developers to create their own `Scrollbar`s on all platforms. In some use cases, a `ScrollController` would need to be provided to the `Scrollbar` and the scrollable widget.

Will this affect my application?

Who is affected
Applications and packages relying on the previous behaviour or signature. Code that uses ScrollBehavior, Scrollbar, GlowingOverscrollIndicator and related APIs.
Practical impact
Behaviour or API differences that can break builds or change runtime behaviour.
What action should I take?
Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
APIs mentioned:ScrollBehaviorScrollbarGlowingOverscrollIndicatorMaterialScrollBehaviorCupertinoScrollBehaviorScrollControllerEditableTextListWheelScrollViewPageViewNestedScrollViewMaterialApp.scrollBehaviorCupertinoApp.scrollBehavior

How do I migrate safely?

Before and after (from the official guide)

dart+19−7
Before
1 final ScrollController controller = ScrollController();
2−Scrollbar(
3 controller: controller,
4− child: ListView.builder(
5− controller: controller,
6− itemBuilder: (BuildContext context, int index) {
7− return Text('Item $index');
8− }
9− )
10 );
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
After
1 final ScrollController controller = ScrollController();
2+final Widget child = ListView.builder(
3 controller: controller,
4+ itemBuilder: (BuildContext context, int index) {
5+ return Text('Item $index');
6+ }
 
 
 
7 );
8+// Only manually add a `Scrollbar` when not on desktop platforms.
9+// Or, see other migrations for changing `ScrollBehavior`.
10+switch (currentPlatform) {
11+ case TargetPlatform.linux:
12+ case TargetPlatform.macOS:
13+ case TargetPlatform.windows:
14+ return child;
15+ case TargetPlatform.android:
16+ case TargetPlatform.fuchsia:
17+ case TargetPlatform.iOS:
18+ return Scrollbar(
19+ controller: controller,
20+ child: child;
21+ );
22+}
Raw before / after
final ScrollController controller = ScrollController();
Scrollbar(
  controller: controller,
  child: ListView.builder(
    controller: controller,
    itemBuilder: (BuildContext context, int index) {
      return Text('Item $index');
    }
  )
);
final ScrollController controller = ScrollController();
final Widget child = ListView.builder(
  controller: controller,
  itemBuilder: (BuildContext context, int index) {
    return Text('Item $index');
  }
);
// Only manually add a `Scrollbar` when not on desktop platforms.
// Or, see other migrations for changing `ScrollBehavior`.
switch (currentPlatform) {
  case TargetPlatform.linux:
  case TargetPlatform.macOS:
  case TargetPlatform.windows:
    return child;
  case TargetPlatform.android:
  case TargetPlatform.fuchsia:
  case TargetPlatform.iOS:
    return Scrollbar(
      controller: controller,
      child: child;
    );
}
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)

Removing manual Scrollbars on desktop

Code before migration:

final ScrollController controller = ScrollController();
Scrollbar(
  controller: controller,
  child: ListView.builder(
    controller: controller,
    itemBuilder: (BuildContext context, int index) {
      return Text('Item $index');
    }
  )
);

Code after migration:

final ScrollController controller = ScrollController();
final Widget child = ListView.builder(
  controller: controller,
  itemBuilder: (BuildContext context, int index) {
    return Text('Item $index');
  }
);
// Only manually add a `Scrollbar` when not on desktop platforms.
// Or, see other migrations for changing `ScrollBehavior`.
switch (currentPlatform) {
  case TargetPlatform.linux:
  case TargetPlatform.macOS:
  case TargetPlatform.windows:
    return child;
  case TargetPlatform.android:
  case TargetPlatform.fuchsia:
  case TargetPlatform.iOS:
    return Scrollbar(
      controller: controller,
      child: child;
    );
}

Setting a custom ScrollBehavior for your application

Code before migration:

// MaterialApps previously had a private ScrollBehavior.
MaterialApp(
  // ...
);

Code after migration:

// MaterialApps previously had a private ScrollBehavior.
// This is available to extend now.
class MyCustomScrollBehavior extends MaterialScrollBehavior {
  // Override behavior methods like buildOverscrollIndicator and buildScrollbar
}

// ScrollBehavior can now be configured for an entire application.
MaterialApp(
  scrollBehavior: MyCustomScrollBehavior(),
  // ...
);

Setting a custom ScrollBehavior for a specific widget

Code before migration:

final ScrollController controller = ScrollController();
ListView.builder(
  controller: controller,
  itemBuilder: (BuildContext context, int index) {
   return Text('Item $index');
 }
);

Code after migration:

// MaterialApps previously had a private ScrollBehavior.
// This is available to extend now.
class MyCustomScrollBehavior extends MaterialScrollBehavior {
  // Override behavior methods like buildOverscrollIndicator and buildScrollbar
}

// ScrollBehavior can be set for a specific widget.
final ScrollController controller = ScrollController();
ScrollConfiguration(
  behavior: MyCustomScrollBehavior(),
  child: ListView.builder(
    controller: controller,
    itemBuilder: (BuildContext context, int index) {
     return Text('Item $index');
    }
  ),
);

Copy and modify existing ScrollBehavior

Code before migration:

final ScrollController controller = ScrollController();
ListView.builder(
  controller: controller,
  itemBuilder: (BuildContext context, int index) {
   return Text('Item $index');
 }
);

Code after migration:

// ScrollBehavior can be copied and adjusted.
final ScrollController controller = ScrollController();
ScrollConfiguration(
  behavior: ScrollConfiguration.of(context).copyWith(scrollbars: false),
  child: ListView.builder(
    controller: controller,
    itemBuilder: (BuildContext context, int index) {
     return Text('Item $index');
    }
  ),
);
Migration assistantAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.

Evidence & verification

Official migration guide·Verified classification (95%)

Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).

An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.

Source commit
b3045439b7c0
Source last updated
Oct 21, 2026
Last synchronized
Oct 21, 2026
Publication status
published
Publication history
  • Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI explanationAI-generated · grounded in cited sources
AI explanations are not configured
Set AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.
Was this useful?