smooth_sheets

• fix: Prevent sheet from exceeding bounds when dragging non-overflowing scrollable content (#613) - 12e3a1c

• build: Bump navigator_resizable from 3.0.2 to 3.1.0 to fix these issues: (#605) - f315d5d
  • A crash that occurs in the middle of a route transition.
  • An assertion error when multiple routes are popped while a push transition is still running.
• build: Bump the minimum supported Flutter SDK version to 3.41.0.

• fix: Avoid Widget Inspector crash on drag-disabled sheets (#595) - beb86c7

• fix: SheetContentScaffold semantics child order matches paint order so overlapping bars are not obscured by assistive technologies
• fix: Avoid crash when a SheetModel is detached during layout

Add sheetVisibility to ModalSheetRouteMixin

ModalSheetRouteMixin.sheetVisibility has been added, an Animation<double> that reports how much of the sheet is visible in a modal route. It can be used, for example, to easily create custom modal barriers that change its opacity or blurriness based on the sheet's visibility, something like this:

See the API documentation and this example for more details.

Bug fixes

• fix: Modal barrier fade too subtle for small sheets (#577) - 473daa9
• fix: Null check operator error in _LazySheetModelView.setModel due to uninitialized old model offset (#571) - bbdc96c

• fix: Assertion error in SheetContentScaffold when height is zero (#558) - ba7bd77

• fix: False positive layout overflow assertion

• fix: Avoid constraint violation and report layout overflow in SheetContentScaffold (#539) - 488b569

The first stable release of smooth_sheets!

This version mainly focuses on bug fixes to stabilize the package, but some small new features have also shipped. Breaking changes are marked with a 💥 — please follow the migration guides.

Add PagedSheetRouteTheme for inheritable route defaults

A new PagedSheetRouteTheme lets you set shared defaults for all routes in a PagedSheet. Place it above PagedSheet to configure scrollConfiguration, dragConfiguration, initialOffset, snapGrid, transitionDuration, and transitionsBuilder once, instead of repeating them on every route.

PagedSheetRouteTheme(
  data: PagedSheetRouteThemeData(
    transitionsBuilder: myTransitionBuilder,
    snapGrid: mySnapGrid,
  ),
  child: PagedSheet(
    navigator: Navigator(...),
  ),
)

Routes inherit from the theme when their parameter is null. Per-route values always take precedence.

scrollConfiguration: null on routes now means "inherit" 💥

Previously, scrollConfiguration: null on a PagedSheetRoute or PagedSheetPage meant "no scroll-sheet integration." Now it means "inherit from PagedSheetRouteTheme." To explicitly disable scroll-sheet integration, use SheetScrollConfiguration.disabled:

BEFORE:

PagedSheetRoute(
  scrollConfiguration: null, // No scroll-sheet integration
  builder: (_) => MyContent(),
)

AFTER:

PagedSheetRoute(
  scrollConfiguration: SheetScrollConfiguration.disabled,
  builder: (_) => MyContent(),
)

dragConfiguration: null on routes now means "inherit" 💥

The same rule as scrollConfiguration is now applied to dragConfiguration on PagedSheetRoute and PagedSheetPage. Specify SheetDragConfiguration.disabled instead of null to disable dragging for a route.

Route parameters are now nullable

initialOffset, snapGrid, and transitionDuration on PagedSheetRoute and PagedSheetPage are now nullable. When null, they inherit from PagedSheetRouteTheme. The built-in defaults (when no theme is provided) are unchanged.

New way to manage scroll controllers 💥

Previously, there was no way to manage a scroll controller for a scrollable widget inside a sheet from outside of it. A workaround was to use SheetScrollable and capture the controller in the builder callback, but this approach was not aligned with the widget's lifecycle.

With the updated SheetScrollable, you can now create a SheetScrollController outside the sheet (a specialized ScrollController) and attach it to SheetScrollable, just as you would with a regular ScrollController.

BEFORE:

ScrollController? scrollController;

Widget build(BuildContext context) {
  return Sheet(
    child: SheetScrollable(
      builder: (context, controller) {
        scrollController = controller;
        return ListView(
          controller: controller,
          children: [...],
        );
      },
    ),
  );
}

AFTER:

late final SheetScrollController scrollController;

@override
void initState() {
  super.initState();
  scrollController = SheetScrollController();
}

void dispose() {
  scrollController.dispose();
  super.dispose();
}

Widget build(BuildContext context) {
  return Sheet(
    child: SheetScrollable(
      controller: scrollController,
      child: ListView(
        children: [...],
      ),
    ),
  );
}

Other changes

Sheet.dragConfiguration is now non-nullable 💥

Similar to PagedSheet, the dragConfiguration property on Sheet is now non-nullable. If you were passing null to disable dragging, use SheetDragConfiguration.disabled instead.

BEFORE:

Sheet(
  dragConfiguration: null, // Disabled dragging
  child: MyContent(),
)

AFTER:

Sheet(
  dragConfiguration: SheetDragConfiguration.disabled,
  child: MyContent(),
)

BouncingSheetPhysics no longer accepts custom spring 💥

The spring parameter has been removed from the BouncingSheetPhysics constructor as part of a fix for #435. If you were using a custom spring, you can extend BouncingSheetPhysics and override the spring getter to return your custom value.

BEFORE:

BouncingSheetPhysics(spring: customSpring);

AFTER:

class MyPhysics extends BouncingSheetPhysics {
  MyPhysics({super.bounceExtent, super.resistance});

  @override
  SpringDescription get spring => customSpring;
}

Default HitTestBehavior changed from translucent to opaque 💥

The default hitTestBehavior in SheetDragConfiguration has changed from HitTestBehavior.translucent to HitTestBehavior.opaque, so that the sheet can be dragged out of the box even from transparent areas such as padding.

And more...

• kDefaultSheetSpring has been removed from the public API 💥
• PagedSheet's shared elements (e.g., app-bar and bottom-bar) are now also affected by the current route's drag configuration (#500) 💥
• feat: Use drag devices from inherited scroll config (#513) - 0796b1a by @Zekfad
• feat: Add deviceKinds to SheetDragConfiguration (#528) - 5a76bba
• fix: Android predictive back gesture triggers jaggy route pop animation in PagedSheet (#526) - 6dd9f3f
• fix: Assertion error occurs when predictive back gesture commits route pop on Android (#525) - 77fe2c0
• fix: Inconsistent BouncingSheetPhysics resistance in over-drag vs. ballistic animation (#522) - 0e74132
• fix: SteplessSnapGrid ignores on-screen keyboard appearance (#515) - b872c74
• fix: Navigator.replace does not update position and size of PagedSheet (#508) - 9b38b6c
• fix: Account for viewPadding in SheetContentScaffold bar constraints (#507) - e133442
• fix: Ballistic animation ends abruptly right after releasing over-dragged sheet (#506) - 4c4bf56

This version introduces a padding property on Sheet and PagedSheet, giving you full control over how the sheet content responds to the keyboard, safe areas, or any other insets.

Context

Previously, Sheet and PagedSheet offered two boolean flags — shrinkChildToAvoidDynamicOverlap and shrinkChildToAvoidStaticOverlap — to control whether a sheet automatically resizes its child to avoid the on-screen keyboard or screen notches. While they worked well in many cases, there are still cases those two flags can't cover — for example, a floating sheet with margins where the bottom margin changes depending on whether the keyboard is open.

What's new?

A padding property has been added to Sheet and PagedSheet widgets to replace the two flags. This change also eliminates the automatic content resizing behavior, so you are now responsible for padding the sheet content to avoid the keyboard and screen notches.

Although it may sound like a downgrade, it enables you to build more complex layouts that couldn't be achieved with the legacy flags. Here's an example of such a layout where the sheet avoids screen notches when first displayed, then shifts itself above the keyboard when it opens while preserving a fixed amount of space between the keyboard and the sheet. Weirdly, this wasn't possible because shrinkChildToAvoidDynamicOverlap interfered with SheetViewport.padding, completely ignoring the padding when the keyboard was shown.

See sheet_padding.dart for more examples.

Sheet.padding vs. SheetViewport.padding vs. Padding widget

You might wonder how Sheet.padding differs from SheetViewport.padding and wrapping the sheet content (Sheet.child) with a Padding widget from the Flutter SDK. While this interactive example is useful for understanding the differences visually, here's a TL;DR:

• use Sheet.padding to inset the content,
• use SheetViewport.padding to add margin around the sheet itself, and
• wrapping the content with a Padding widget doesn't fit most cases.

Breaking Changes

The shrinkChildToAvoidDynamicOverlap and shrinkChildToAvoidStaticOverlap flags on Sheet and PagedSheet have been removed. Please follow the instructions below to migrate from these two flags to the padding property. The basic rules are to replace:

• shrinkChildToAvoidDynamicOverlap: true with a padding of MediaQuery.viewInsetsOf(context).bottom
• shrinkChildToAvoidStaticOverlap: true with a padding of MediaQuery.viewPaddingOf(context).bottom

For sheets with shrinkChildToAvoidDynamicOverlap: true

You may have enabled shrinkChildToAvoidDynamicOverlap to automatically shift the sheet content upward to avoid the keyboard. It was true by default, so sheets that don't explicitly disable this flag should also migrate to the padding property as follows:

BEFORE

Sheet(
  shrinkChildToAvoidDynamicOverlap: true,
  child: ...,
);

AFTER

Sheet(
  padding: EdgeInsets.only(
  	bottom: MediaQuery.viewInsetsOf(context).bottom,
  ),
  child: ...,
);

For sheets with shrinkChildToAvoidStaticOverlap: true

Follow this migration guide if you enabled shrinkChildToAvoidStaticOverlap to automatically pad the content to avoid screen notches at the bottom. It was false by default, so sheets that don't explicitly enable this flag are not affected by this change.

BEFORE

Sheet(
  shrinkChildToAvoidStaticOverlap: true,
  child: ...,
);

AFTER

Sheet(
  padding: EdgeInsets.only(
  	bottom: MediaQuery.viewPaddingOf(context).bottom,
  ),
  child: ...,
);

For sheets with both shrinkChildToAvoidDynamicOverlap: true and shrinkChildToAvoidStaticOverlap: true

BEFORE

Sheet(
  shrinkChildToAvoidDynamicOverlap: true,
  shrinkChildToAvoidStaticOverlap: true,
  child: ...,
);

AFTER

Sheet(
  padding: EdgeInsets.only(
    bottom: math.max(
      MediaQuery.viewInsetsOf(context).bottom,
      MediaQuery.viewPaddingOf(context).bottom,
    ),
  ),
  child: ...,
);

Other Breaking Changes

The following properties have also been removed:

• SheetMetrics.viewportDynamicOverlap
  • Use MediaQuery.viewInsetsOf(context).bottom from descendant widgets of a sheet instead.
• SheetMetrics.viewportStaticOverlap
  • Use MediaQuery.viewPaddingOf(context).bottom from descendant widgets of a sheet instead.
• SheetLayoutSpec.viewportDynamicOverlap
  • Use MediaQuery.viewInsetsOf(context).bottom from descendant widgets of a sheet instead.
• SheetLayoutSpec.viewportStaticOverlap
  • Use MediaQuery.viewPaddingOf(context).bottom from descendant widgets of a sheet instead.
• SheetLayoutSpec.shrinkContentToAvoidDynamicOverlap
• SheetLayoutSpec.shrinkContentToAvoidStaticOverlap

This version includes several new features, fixes and breaking changes (denoted with 💥).

Added Custom Barrier Support for Modal Sheets

ModalSheetRoute.barrierBuilder has been added to modal routes and pages (thank you, @bqubique). This allows you to build a custom barrier for a modal sheet—for example, a blurred background. See this example for more practical usage.

ModalSheetRoute(
  ...
  barrierBuilder: (route, dismissCallback) {
    return GestureDetector(
      onTap: dismissCallback,
      child: BackdropFilter(
        filter: ImageFilter.blur(sigmaX: 15.0, sigmaY: 15.0),
        child: Container(color: Colors.black12),
      ),
    );
  },
);

Simplified BouncingSheetPhysics configuration 💥

The way to configure the bouncing behavior of a sheet is now much more straightforward. There are only two parameters: bounceExtent and resistance. bounceExtent is the maximum number of pixels the sheet can be overdragged, and resistance is a factor that controls how easy or hard it is to overdrag the sheet by bounceExtent pixels. The higher the resistance value, the harder it is to overdrag further.

Examples

Use the tweak bouncing effect example to find the best values for your use case. Here are some examples:

Breaking Changes

The following legacy APIs have been removed:

• BouncingBehavior
• DirectionAwareBouncingBehavior
• FixedBouncingBehavior
• BouncingSheetPhysics.behavior
• BouncingSheetPhysics.frictionCurve

Unfortunately, there is no straightforward way to migrate from the old APIs to resistance and bounceExtent parameters while keeping exactly the same bouncing behavior.

Enable dynamic viewport padding for modal sheets 💥

A viewportBuilder has been added to modal sheet routes and pages. It builds a SheetViewport for a modal sheet, allowing SheetViewport.padding to depend on BuildContext and dynamically change based on system UI elements like the on-screen keyboard.

You may think this change isn't very useful since the current SheetViewport only has a padding property. However, as more features like #3 are added to SheetViewport, you'll see more benefits from this change.

Breaking Changes

The viewportPadding property has been removed from modal sheet routes and pages. Use viewportBuilder instead and specify the padding directly via SheetViewport.padding.

BEFORE

ModalSheetRoute(
  viewportPadding: EdgeInsets.only(
    top: MediaQuery.viewPaddingOf(context).top,
  ),
  builder: (context) => Sheet(...),
);

AFTER

ModalSheetRoute(
  viewportBuilder: (context, child) {
    return SheetViewport(
      padding: EdgeInsets.only(
        top: MediaQuery.viewPaddingOf(context).top,
      ),
      // The child is the widget built by the builder callback.
      child: child,
    );
  },
  builder: (context) => Sheet(...),
);

Stabilized Sheet Behaviors

This release also includes several improvements to sheet behaviors in response to user gestures:

• fix: Unexpected bouncing animation with ClampingScrollPhysics #363
• fix: Inconsistent BouncingSheetPhysics behavior with keyboard state #389

Removed thresholdVelocityToInterruptBallisticScroll 💥

SheetScrollConfiguration.thresholdVelocityToInterruptBallisticScroll has been removed. This option was part of the public API and configurable, but it never actually affected the sheet's behavior.

🎉 Added dismissalOffset: A more intuitive and powerful way to define the threshold for swipe-to-dismiss actions on modals

Reported in #303, fixed in #415 thanks to @bjartebore

Previously, we used SwipeDismissSensitivity.minDragDistance to define how many pixels the user had to drag down the modal sheet to close it. However, since it only accepted a threshold distance in logical pixels, it was difficult to create a consistent UX across various device sizes and sheet sizes.

SwipeDismissSensitivity.dismissalOffset has been introduced as a replacement for minDragDistance and tackle this problem. It allows us to define the modal's dismissal threshold in terms of SheetOffset, below which the sheet will be dismissed when the drag ends. This change provides much greater control over when sheets should be dismissed, allowing thresholds to depend on percentages, absolute pixels, or even custom logic that adapts to content size or viewport dimensions.

Usage:

// Dismiss if only 40% or less of the sheet is visible when the drag ends
const SwipeDismissSensitivity(dismissalOffset: SheetOffset(0.4));

// Dismiss if only 200 pixels or less of the sheet is visible when the drag ends
const SwipeDismissSensitivity(dismissalOffset: SheetOffset.absolute(200));

// Dismiss if the sheet is in the bottom half of the screen when the drag ends
const SwipeDismissSensitivity(dismissalOffset: SheetOffset.proportionalToViewport(0.5));

// Custom threshold for more complex use cases
const SwipeDismissSensitivity(dismissalOffset: CustomThreshold());

class CustomThreshold implements SheetOffset {
  const CustomThreshold();
  
  @override
  double resolve(ViewportLayout metrics) {
    return max(metrics.contentSize.height * 0.5, 80);
  }
}

Migrating from minDragDistance

Unfortunately, there's no straightforward way to migrate from minDragDistance to dismissalOffset as they represent different thresholds. While minDragDistance describes how many pixels the user has to drag the sheet to dismiss the modal, dismissalOffset defines the distance from the bottom edge of the route's viewport to the top edge of the sheet, below which the sheet will dismiss when the drag ends.

This is a special case, but if you know the sheet's height in advance, it's possible to migrate to the new API while keeping the current behavior. For example, if the sheet's height is 500 and the minDragDistance is 100, you can set dismissalOffset to SheetOffset.absolute(500 - 100).

Other changes

• fix: NavigatorEventObserver assertion error when pop during push transition (#416) - 4004500

New Contributors

• @bjartebore made their first contribution in #415

Full Changelog: v0.14.0...v0.15.0

🎉 New Features

Cupertino Modal Sheet Overlay Effect

Reported in #25, fixed in #403

We've added support for toning overlay effects on Cupertino-style modal sheets when stacking them, matching native iOS behavior. The new overlayColor parameter in CupertinoModalSheetPage and CupertinoModalSheetRoute allows applying a subtle overlay to background sheets when another sheet is presented, creating a more authentic iOS experience and improving visual hierarchy, especially in dark mode.

Usage:

CupertinoModalSheetPage(
  overlayColor: const Color(0x33ffffff), // A translucent white color
  child: MySheetContent(),
)

Pull-to-Refresh Support in Sheets

Reported in #264, fixed in #402

We've added support for pull-to-refresh functionality and overscroll effects within sheets through the new delegateUnhandledOverscrollToChild flag in SheetScrollConfiguration. When enabled, this flag allows overscroll deltas that aren't handled by the sheet's physics to be passed to child scrollable widgets, enabling RefreshIndicator and BouncingScrollPhysics effects to work seamlessly within sheet content.

This feature maintains backward compatibility and requires explicit opt-in, ensuring no impact on existing code.

🐛 Bug Fixes

Fixed Sheet Position During Window Resize

Reported in #399, fixed in #400

Fixed an issue where sheets would not maintain their proper position when the app window was resized, particularly when dragging the bottom border to expand the window downward. Previously, sheets would appear to "float" rather than staying correctly positioned relative to the window boundaries.

This issue was especially noticeable on desktop platforms and also occurred on Android when running in Picture-in-Picture mode with keyboard interactions. The fix ensures that sheets now properly track window size changes and maintain their relative position, providing a more consistent user experience across different window configurations.

Full Changelog: v0.13.0...v0.14.0

• feat: Add SheetScrollHandlingBehavior for precise control over scroll gesture handling (#393) - ee7f2a6
• feat: Add utility functions to show modal sheets (#380) - 25a901c

See the release note for more details.

• feat: Add SheetPopScope to enable/disable the swipe gesture in modals from within build method (#359) - 6766534
• fix: Crashes when popping a non-modal sheet route just below a modal sheet route (#357) - cb9a174

See the release note for more details.

• fix: SheetNotification not dispatched during PagedSheet route transitions (#352) - 609ac4b

See the release note for more details.

• fix: Assertion error when push CupertinoModalSheetRoute during closing animation (#347) - 0dbf6ee
• fix: Changing swipeDismissible dynamically causes a layout error (#344) - 3aeb05b

See the release note for more details.

• fix: PagedSheet cannot be dragged when the drag starts at shared top/bottom bar built in builder callback (#323) - 2ba8d35
• fix: Unstable route transition in PagedSheet when pop a route during snapping animation (#322) - 62e96ee
• fix: PagedSheet ignores initialOffset when using auto_route and the first page is fullscreen (#321) - cdecf41

See the release note for more details.

• fix: Bottom bar is hidden despite BottomBarVisibility.always(ignoreBottomInset: true) (#313) - faa7883

See the release note for more details.

• fix: Initial offset of PagedSheet is ignored when using auto_route (#310) - fd83555

See the release note for more details.

This version contains breaking changes. See the migration guide for more details.

[!IMPORTANT] Version 0.11.x requires Flutter SDK version 3.27.0 or higher.

Bug fixes

• Question about sheet draggable #300
• StickyBottomBarVisibility positioned incorrectly for constrained sheets #297
• StickyBottomBarVisibility bottom bar hidden when used in navigation #292
• Using go_router.go() method to close a sheet don't seems to reset animation state #211

New features

• Add option to stretch actual sheet height when overdragging #286
• Add margin property to sheet widget #282
• Support iOS native modal sheet stretching behavior #169
• Support transparent space around sheet #76

Improvements

• Reimplement CupertinoModalSheetRoute and Page with ModalRoute.delegatedTransition #293
• Merge ScrollableSheet and DraggableSheet into a single widget to simplify the API and codebase #285
• Support shared bottom & top bars in NavigationSheet #280
• Make sheet size independent of its child size #278
• Refine sheet structure and public APIs #276
• Make NavigationSheet independent of NavigatorObserver #172

This version contains breaking changes. See the migration guide for more details.

• Fix: Touch is ignored issue not fixed for top edge (#212)
• Fix: Closing keyboard slows down snapping animation (#193)
• Fix: Dynamically changing sheet height doesn't respect snapping constraints (#226)
• Fix: Snapping effect doesn't work when closing keyboard on non-fullscreen sheet (#192)
• Fix: Unwanted bouncing when opening or closing the on-screen keyboard on ScrollableSheet (#245)

• Add SwipeDismissSensitivity, a way to customize sensitivity of swipe-to-dismiss action on modal sheet (#222)

• Fix: Press-and-hold gesture in PageView doesn't stop momentum scrolling (#219)

• Fix: Keyboard visibility changes disrupt route transition animation in NavigationSheet (#215)

• Fix: Sometimes touch is ignored when scrollable sheet reaches edge (#209)

This version contains some breaking changes. See the migration guide for more details.

• Dispatch a notification when drag is cancelled (#204)
• Prefer composition style for SheetKeyboardDismissible (#197)
• Fix: NavigationSheet throws assertion error when starting to scroll in list view during page transition (#199)
• Refactor notification dispatch mechanism (#202)
• Fix: Momentum scrolling continues despite press and hold in list view (#196)
• Refactor: Lift sheet context up (#201)

• Fix: Opening keyboard interrupts sheet animation (#189)

• Fix: Cupertino style modal transition not working with NavigationSheet (#182)

This version contains some breaking changes. See the migration guide for more details.

• Make stretching behavior of StretchingSheetPhysics more customizable (#171)
• Rename "stretching" to "bouncing" (#173, #177)
• Fix: bouncing physics doesn't respect bounds where sheet can bounce (#178)

• Fix: DropdownButton doesn't work in NavigationSheet (#139)

• Fix: Attaching SheetController to NavigationSheet causes "Null check operator used on a null value" (#151)
• Fix: SheetController attached to NavigationSheet always emits minPixels = 0.0 (#163)

• Fix: Unwanted bouncing effect when opening keyboard on NavigationSheet (#153)

This version contains some breaking changes. See the migration guide for more details.

• Fix: Unable to build with Flutter versions < 3.22.0 (#141)
• Increase min SDK versions (#147)
• Remove basePhysics from SheetThemeData (#148)

This version contains some breaking changes. See the migration guide for more details.

• SheetDismissible not working with NavigationSheet (#137)
• Add a way to handle dismissing modal sheet events in one place (#130)
• SheetDismissible never trigger pull-to-dismiss action if ListView's scroll offset is halfway (#84)
• SheetDismissible not working with infinite looping scroll widget (#80)
• Can't overdrag modal sheet during pull-to-dismiss action (#53)
• Sometimes Pull-to-dismiss action is not triggered on modal sheet (#52)

• Fix an assertion error when specific page transition scenarios in declarative 'NavigationSheet' (#94)

• Fix a crash during the first build of NavigationSheet with a path that contains multiple routes such as /a/b/c (#109)

• Re-export NavigationSheetRoute that is unintentionally omitted in v0.5.0 (#110)

This version contains some breaking changes. See the migration guide for more details.

• Attach default controller to sheet if not explicitly specified (#102)
• Reimplement core architecture (#106)

• Add new SheetNotifications for drag events (#92)
• Add SheetTheme (#93)
• Add a way to specify default physics and default ancestor physics (#96)

• Fix mistakes in the documentation of BottomBarVisibility and ConditionalStickyBottomBarVisibility which may mislead readers.

• Add BottomBarVisibility widgets (#15, #19)

• Fix crash when clicking on the modal barrier while dragging the sheet (#54)

• Add InterpolationSimulation (#55)

• Documentation updates

• Documentation updates

• Add iOS 15 style modal sheet transition (#21)
• Improve the sheet motion while opening/closing the keyboard (#27)
• Add settings and fullscreenDialog params to the constructors of modal sheet routes and pages (#28)
• Physics improvements (#32)
• Add conditional modal sheet popping feature (#39)
• Remove enablePullToDismiss (#44)

• Add a showcase that uses TextFields in a sheet (#2)
• Dispatch a Notification when the sheet extent changes (#4)
• Add a way to dismiss the on-screen keyboard when the sheet is dragged (#8)

• Initial release