A modal bottom sheet looks like a simple thing until you put a list inside it. The user drags down on the list: should the list scroll, or should the sheet move? If the list is at its top, the sheet should follow the finger and the list should stay still. If the user changes direction, the sheet should come back up before the list starts scrolling. Getting this handoff wrong gives you content that slides inside the sheet, or a jump when the drag reverses.
Then come the other details: the keyboard, the safe area, the Android back gesture, a PopScope that wants to block closing, and a router that expects a Page, not a function call.
sheet_route is a Flutter package that treats a modal bottom sheet as a real route. It ships Material, bar and iOS-style sheets, drag to dismiss that cooperates with inner scroll views, snap points, and Page classes for Navigator.pages and go_router.
What it does
Four ways to show a sheet. showSheet is the base function, where you can bring your own decoration with containerBuilder. showMaterialStyleSheet, showBarSheet and showCupertinoStyleSheet give you the three common looks. Each one returns a Future with the value the sheet was popped with.
Real routes and pages. SheetRoute and CupertinoSheetRoute work with Navigator.push. SheetPage and CupertinoSheetPage work with Navigator.pages and with go_router's pageBuilder, so a sheet can have its own path.
Drag to dismiss that works with lists. The drag cooperates with an inner ListView, GridView or CustomScrollView. When the list is at its top, dragging down moves the sheet and the list stays still, with any scroll physics. Dragging back up restores the sheet before the list scrolls. The package does this by routing the drag through the list's ScrollPosition before the physics run.
Snap points. Pass snapPoints: [0.4, 0.7, 1.0] and the sheet rests at those fractions of the available height. A fling moves it to the next snap point.
The iOS "previous route scales back" effect. It is built on ModalRoute.delegatedTransition, so you don't need a wrapper widget or a special page route below the sheet. Stacked sheets scale too.
Keyboard and safe area. The sheet stays above the keyboard, and the inner content sees viewInsets.bottom == 0, so padding is never applied twice. The sheet never covers the status bar, and with useSafeArea the content avoids the home indicator.
Closing rules you can trust. isDismissible: false blocks the barrier, the system back button and the predictive back gesture. A PopScope inside the sheet can veto drag, fling, barrier and back, and its onPopInvokedWithResult is called. On Android, predictive back previews the gesture on the sheet and closes it on commit.
Accessibility and layout direction. The sheet is a named route scope for semantics, and the barrier carries a dismiss label and a tap action. RTL layouts and reduced motion (MediaQueryData.disableAnimations) are supported.
Callbacks. onDragUpdate reports the visible extent while dragging, and onDismiss is called when the sheet closes without a result.
How to use it
Add it from GitHub:
dependencies: sheet_route: git: https://github.com/AbdeldjalilChougui/sheet_route It requires Flutter 3.27 or later, the first release with ModalRoute.delegatedTransition.
A Material-style sheet that returns a value:
import 'package:flutter/material.dart'; import 'package:sheet_route/sheet_route.dart'; Future<void> pickAction(BuildContext context) async { final String? action = await showMaterialStyleSheet<String>( context: context, showDragHandle: true, builder: (BuildContext context) => Column( mainAxisSize: MainAxisSize.min, children: <Widget>[ ListTile( title: const Text('Share'), onTap: () => Navigator.of(context).pop('share'), ), ], ), ); debugPrint('picked $action'); } A sheet with snap points:
showSheet<void>( context: context, snapPoints: const <double>[0.4, 0.7, 1.0], initialSnapPoint: 0.4, topRadius: const Radius.circular(16), builder: (BuildContext context) => ListView(children: const <Widget>[]), ); And an iOS-style sheet as a go_router page:
GoRoute( path: 'details', pageBuilder: (BuildContext context, GoRouterState state) => CupertinoSheetPage<void>(key: state.pageKey, child: const Details()), ), The primary scroll view inside the sheet picks up the sheet's controller on its own. A scroll view that is not the primary one (a nested list, a list with its own controller, or any list on desktop, where PrimaryScrollController is not inherited automatically) can opt in:
ListView(controller: SheetRoute.scrollControllerOf(context), children: items); The main options are expand (fill the available height instead of sizing to the content), isDismissible, enableDrag, closeProgressThreshold (close on release when less than this fraction is visible, 0.6 by default), duration and animationCurve for the open and close animation, plus the usual styling options such as backgroundColor, shape and topRadius. User drags are always linear.
Coming from modal_bottom_sheet
The README has a full migration table. The short version: showMaterialModalBottomSheet becomes showMaterialStyleSheet, showBarModalBottomSheet becomes showBarSheet, showCupertinoModalBottomSheet becomes showCupertinoStyleSheet, and ModalScrollController.of(context) becomes SheetRoute.scrollControllerOf(context), which you usually don't need. MaterialWithModalsPageRoute and CupertinoScaffold are simply removed, because any PageRoute below the sheet scales back. WillPopScope and shouldClose are replaced by PopScope.
Some options are gone: bounce (drags past the top are clamped), secondAnimation, previousRouteAnimationCurve, transitionBackgroundColor and overlayStyle (wrap the content in an AnnotatedRegion<SystemUiOverlayStyle> instead).
Things to know
- Snap points move the sheet, they don't resize it. At a lower snap point, the bottom part of the content is off screen. Put important actions near the top, or use a scroll view.
- Lists that don't use the sheet's controller behave differently. They can still drag the sheet down through their overscroll at the top edge with clamping physics, but dragging back up then scrolls the list instead of lifting the sheet, and with bouncing physics they bounce instead. Wheel pickers (
ListWheelScrollView) and horizontal scroll views never move the sheet. - The previous-route effect has a scope. It applies only to routes in the same
NavigatorwhosecanTransitionToaccepts the sheet.PageRoute,MaterialPageRoute,CupertinoPageRouteand go_router pages all do. WithuseRootNavigator: trueand a nested navigator, only the root navigator's top route scales. -
SheetPageupdates refresh onlychild. When a page is updated with the same key, the other options stay as they were when the route was created. -
isDismissible: falsealso blocks back actions: the system back button,Navigator.maybePopand predictive back.enableDragstill controls dragging. - A name clash. Flutter's cupertino library (3.29+) also declares a
CupertinoSheetRoute. In a file that imports both, useimport 'package:flutter/cupertino.dart' hide CupertinoSheetRoute;. - What was tested. The behaviour differences from the old package are each covered by a widget test (the scroll "jump regression",
PopScopeinside the sheet, keyboard layout). Drag gestures were verified with widget tests. They have not been measured on physical devices.
Why I built it
The README describes the problem through its comparison with modal_bottom_sheet. That package reacted to scroll notifications after the list had already moved, so with bouncing physics the content slid inside the sheet or jumped when the drag reversed. Its route also relied on hasScopedWillPopCallback and willPop(), deprecated in Flutter 3.12, and on onPopInvoked, which was replaced later. Because of that, a PopScope in the sheet was ignored or crashed on newer Flutter. And the iOS-style sheet needed a CupertinoScaffold around the app, and threw a null-check error without it.
I wanted sheets that follow current Flutter APIs: popDisposition and onPopInvokedWithResult for closing, ModalRoute.delegatedTransition for the scale-back effect, and the list's own ScrollPosition for the drag handoff. I also wanted Page classes in the same package, so the same sheet works with Navigator.push and with go_router.
Get the code
The source, the migration table, the tests and an example/ app that demos every style and feature are on GitHub: https://github.com/AbdeldjalilChougui/sheet_route. It is MIT licensed. Issues and pull requests are welcome.
Originally published at abdeldjalilchougui.biz.