CupertinoSheetRoute with scrolling and dragging #177337

MitchellGoodwin · 2025-10-21T18:01:12Z

Fixes #161687

Enables scrollable content within the sheet to work together with the dragging animation.

Flutter:

Screen.Recording.2025-11-25.at.2.14.02.PM.mov

Native:

Screen.Recording.2025-10-16.at.1.42.10.PM.mov

Fling when scrolling to the top vs fling when the scrollable content is already at the top

Screen.Recording.2025-11-25.at.2.16.13.PM.mov

When scrolling is enabled, then the sheet will no longer have a drag gesture recognizer over the sheet content, and will instead rely on the scrollable content to trigger the drag. A non-scrolling area can be wrapped with CupertinoSheetDragArea to put a drag gesture recognizer only on that area, convenient for navbars. See cupertino_sheet.3.dart for a full example.

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

lukepighetti · 2025-10-21T20:00:10Z

missing one minor bit of fidelity. if you are scrolled down and fling to the top it should spring at the top instead of slam to a halt

MitchellGoodwin · 2025-10-21T20:16:02Z

The physics when scrolling to the top is definitely not there yet. It either stops suddenly or bounces when it shouldn't when the drag to dismiss happens. I opened this draft PR to get some feedback on the overall approach.

Piinks · 2025-10-22T20:38:54Z

packages/flutter/lib/src/cupertino/sheet.dart

+    return Navigator.of(context, rootNavigator: true).push<T>(route);
  } else {
-    widgetBuilder = (BuildContext context) {
+    Widget nestedNavigationContent(Widget child) {


Since this is changed to define an inline function, is the else necessary?

Piinks · 2025-10-22T20:39:30Z

packages/flutter/lib/src/cupertino/sheet.dart

-    context,
-    rootNavigator: true,
-  ).push<T>(CupertinoSheetRoute<T>(builder: widgetBuilder, enableDrag: enableDrag));
+    final PageRoute<T> route = effectiveBuilder != null


Can you simplify the logic to de-dupe and call on your new wrapper method based on useNestedNavigation?

Piinks · 2025-10-22T20:48:08Z

packages/flutter/lib/src/cupertino/sheet.dart

+  }
+}
+
+class _NeverUserScrollableScrollPhysics extends ScrollPhysics {


Why is this needed over using NeverScrollableScrollPhysics?

I didn't want to set allowImplicitScrolling to false.

Piinks · 2025-11-25T21:56:18Z

packages/flutter/lib/src/cupertino/sheet.dart

-          child: _CupertinoSheetScope(child: builder(context)),
+          child: Builder(
+            builder: (BuildContext context) {
+              return _CupertinoSheetScope(sheetContext: context, child: _effectiveBuilder(context));


Why do we need to pass around context? That's an anti-pattern.

Ultimately it's so that _CupertinoDragGestureDetector is able to figure out the height of the sheet for knowing how much to adjust the page transition in response to a user drag.

It gets there through CupertinoSheetDragArea looking up the _CupertinoSheetScope above it and passing along the context to _CupertinoDragGestureDetector.

Yeah, it's really not something we should do. Passing around build context is not safe. DraggableScrollableSheet keeps track of the sheet's extent. Are we able to do that here?

I think I can change it so that _CupertinoSheetScope tracks the height/extent rather than the context and that'll work pretty smoothly.

chunhtai

For Accessibility, we would need to focus on two things

dismissable

in talkback this is fine as user can do gesture down and left to issue a android back.

For voiceOver though, it is two fingers Z gesture and it calls Semantics(onDismiss). Looking at the semantics tree, I didnt see the semantics action is set.

the draghandle

In talkback, tap should be able to dismiss the sheet similar to

flutter/packages/flutter/lib/src/material/bottom_sheet.dart

Line 367 in 7b98d50

onSemanticsTap: widget.onClosing,

For voicerOver, we may need to check the iOS behavior, do you know whether there is builtin app that uses the native draggable sheet?

packages/flutter/lib/src/cupertino/sheet.dart

chunhtai · 2025-11-26T17:34:45Z

packages/flutter/lib/src/cupertino/sheet.dart

  bool get enableDrag;

+  /// Determines whether the content can be scrolled.
+  bool get enableScroll;


can this be private?

packages/flutter/lib/src/cupertino/sheet.dart

chunhtai · 2025-11-26T18:06:42Z

also, while not yet wired up in the engine, can you also apply SemanticsRole.dragHandle to the handle so that we won't forget about this in the future when it is wired up

MitchellGoodwin · 2025-12-01T22:35:40Z

For voicerOver, we may need to check the iOS behavior, do you know whether there is builtin app that uses the native draggable sheet?

You can find the native sheet in the Contacts app, when you add a new contact. You can also find another one in the Settings app through General -> Language & Region -> Add Language

MitchellGoodwin · 2025-12-01T22:42:23Z

also, while not yet wired up in the engine, can you also apply SemanticsRole.dragHandle to the handle so that we won't forget about this in the future when it is wired up

CupertinoSheet currently does not add a drag handle. For the native sheet widget, the drag handle is normally added when the sheet is resizable, which CupertinoSheet does not do by default, nor is this PR adding that.

However, CupertinoSheetDragArea could be wrapped around a drag handle type widget manually added by a dev.

So should we either

Not do anything with the drag handle role for this PR.
Add either a isDragHandle or a more generic SemanticsRole property to CupertinoSheetDragArea.
Add an other SemanticsRole somewhere else that I'm missing.

MitchellGoodwin · 2025-12-02T00:17:03Z

@chunhtai

I tested on a device both the native behavior and this code.

On native the two finger Z-scrub gesture does not dismiss the sheet, it seems. Double tap, then drag does dismiss it however.

For CupertinoSheet, currently the Z-scrub gesture does dismiss it, the same with double tap and drag.

Should we block the two finger Z gesture?

Piinks · 2025-12-02T19:12:35Z

CupertinoSheet currently does not add a drag handle. For the native sheet widget, the drag handle is normally added when the sheet is resizable

@MitchellGoodwin have you checked the native behavior with accessibility controls enabled? Does SwiftUI expose the ability to add drag handles?

MitchellGoodwin · 2025-12-02T19:43:11Z

@MitchellGoodwin have you checked the native behavior with accessibility controls enabled? Does SwiftUI expose the ability to add drag handles?

@Piinks I have checked the native behavior with accessibility controls, using a physical device.

For the drag handle on native, they do expose a way to add it through prefersGrabberVisibile. They refer to the drag handle as a "grabber".

From the HIGs documentation on sheets, they say:

"Include a grabber in a resizable sheet. A grabber shows people that they can drag the sheet to resize it; they can also tap it to cycle through the detents. In addition to providing a visual indicator of resizability, a grabber also works with VoiceOver so people can resize the sheet without seeing the screen."

I filled an issue for the drag handle #179358. I think that can be done in a separate PR from this one.

justinmc

Just trying to think through an alternative approach... Rather than a new constructor for CupertinoSheetRoute that passes a ScrollController, could you use PrimaryScrollController.of inside of CupertinoSheetRoute and ask users to do the same and pass that to their relevant scroll view? I'm no expert in this area but it seems kind of aligned with the intention of PrimaryScrollController.

If not PrimaryScrollController, then would a new similar InheritedWidget make sense? ...Or would it just make this more complicated and less discoverable?

Otherwise, do you know how this kind of thing works in SwiftUI? Is it always the entire CupertinoSheet that is scrollable?

Assuming none of these drive-by ideas is viable, and that this covers the main use cases from SwiftUI, then this approach looks good to me!

justinmc · 2025-12-05T23:30:22Z

packages/flutter/lib/src/cupertino/sheet.dart

 /// This is a convenience method for displaying [CupertinoSheetRoute] for common,
-/// straightforward use cases. The Widget returned from `pageBuilder` will be
-/// used to display the content on the [CupertinoSheetRoute].
+/// straightforward use cases. There are two different build methods that are provided
+/// by the method for building the content of the [CupertinoSheetRoute]. Use `builder`
+/// if there is no content within the sheet that needs to scroll. This is good
+/// for sheets with a simple display, however scrolling gestures will conflict
+/// with the drag to dismiss gesture. `scrollableBuilder` will enable scrollable
+/// content within the sheet. See [CupertinoSheetRoute.scrollable] for more
+/// information.


Nit: Should you mention that this is for vertical scrolling?

Good callout

justinmc · 2025-12-05T23:55:15Z

examples/api/lib/cupertino/sheet/cupertino_sheet.3.dart

+
+  @override
+  Widget build(BuildContext context) {
+    return CupertinoSheetDragArea(child: child);


Could this be automatically built into CupertinoNavigationBar?

It's possible, and it would be convenient as this would theoretically be a common use case. I'd just worry about this behavior being discoverable.

This does feel a bit kludgy from the developer experience side.

What native behavior are we trying to emulate by exposing this drag wrapper for non-scrolling parts? If I had a header that I wanted to have drag the sheet, why not put it in a pinned sliver in a CustomScrollView as part of the scrollable? Would that achieve the same effect without adding more API for the developer to have to wire up?

What native behavior are we trying to emulate by exposing this drag wrapper for non-scrolling parts?

We want to be able to trigger the drag-to-dismiss behavior when a drag originates outside of the scroll area, and only the drag-to-dismiss, not a scroll. For example, if you start a drag on the header of a native sheet, it will not scroll the content below it, no matter what direction you drag. This is also the only way to trigger the stretch upwards drag effect on a sheet. If you start the drag from within the scrolling area then the draggable/scrollable behavior would happen.

If I had a header that I wanted to have drag the sheet, why not put it in a pinned sliver in a CustomScrollView as part of the scrollable? Would that achieve the same effect without adding more API for the developer to have to wire up?

I believe in that case then a scroll would be triggered on a drag upwards originating in the pinned sliver, instead of the stretch animation.

From native: a drag starting within the navbar will not scroll and will stretch upwards. A drag starting below the navbar will scroll depending on the direction, and will not scroll upwards.

Basically outside of the scrolling area we want the sheet to work as if it's a non-scrolling sheet. This wrapper lets a developer wrap the original vertical drag gesture recognizer only around those areas.

Would it be easier for the developer if, in the case of a scrollable sheet, we provide a header parameter and we can manage the gesture resolution ourselves internally?
What is the native experience like for developers building the UI you described above?

I believe in that case then a scroll would be triggered on a drag upwards originating in the pinned sliver, instead of the stretch animation.

Did you try it?

We have control over how the scrolling offset is applied here with the custom scroll position class in the scrollable sheet, could we divert it in this case?

MitchellGoodwin · 2025-12-06T00:19:42Z

Just trying to think through an alternative approach... Rather than a new constructor for CupertinoSheetRoute that passes a ScrollController, could you use PrimaryScrollController.of inside of CupertinoSheetRoute and ask users to do the same and pass that to their relevant scroll view? I'm no expert in this area but it seems kind of aligned with the intention of PrimaryScrollController.

@justinmc The only issue with that is that we would need to know that the sheet content is intended to be scrollable. So, we could provide the controller with PrimaryScrollController but I think we'd need to have at least a scrollable boolean property in the constructor. When set to true it doesn't apply the drag gesture detector over the whole sheet.

If not PrimaryScrollController, then would a new similar InheritedWidget make sense? ...Or would it just make this more complicated and less discoverable?

I don't think a new widget would be needed. As far the user of this API would be concerned, the scroll controller isn't unique in how they implement it. This would make this API further different from DraggableScrollableSheet, so there's a difference in consistency there.

Otherwise, do you know how this kind of thing works in SwiftUI? Is it always the entire CupertinoSheet that is scrollable?

You can just put a scroll view within the sheet and it works as expected. Scrollable areas in Swift know when they are the child of a resizable area and handle things accordingly. Similarly they are able to have priority over the drag gesture that might be on the rest of the sheet.

The most common use case is that the majority of the sheet, except for the nav bar is scrollable. So the situation in the example.

Piinks · 2025-12-08T23:17:13Z

packages/flutter/lib/src/cupertino/sheet.dart

 /// This is a convenience method for displaying [CupertinoSheetRoute] for common,
-/// straightforward use cases. The Widget returned from `pageBuilder` will be
-/// used to display the content on the [CupertinoSheetRoute].
+/// straightforward use cases. There are two different build methods that are provided


I know this is not exactly part of this change, but lil nit:

Suggested change

/// This is a convenience method for displaying [CupertinoSheetRoute] for common,

/// straightforward use cases. The Widget returned from `pageBuilder` will be

/// used to display the content on the [CupertinoSheetRoute].

/// straightforward use cases. There are two different build methods that are provided

/// This is a convenience method for displaying [CupertinoSheetRoute] for

/// most use cases. There are two different build methods that are provided

Reminded me of https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md#use-the-passive-voice-recommend-do-not-require-never-say-things-are-simple

Follow-up question - what are the less common or straightforward sue bases, and what should people use in those scenarios?

Follow-up question - what are the less common or straightforward sue bases, and what should people use in those scenarios?

showCupertinoSheet adds some boilerplate around nested navigation, and making sure the route is pushed to the right Navigator, which should work for most use cases of both. But for nested navigation in particular there might be configurations that our boilerplate might not fit, so in those cases they would use CupertinoSheetRoute directly and set things up themselves. This includes add-to-app situations with just the sheet, restorable state, custom Navigators, etc.

Piinks · 2025-12-08T23:20:10Z

packages/flutter/lib/src/cupertino/sheet.dart

+  /// Creates a page route that displays an iOS styled sheet that is expected to
+  /// have scrollable content that spans the whole sheet.
+  ///
+  /// When this constructor is used, the content of the sheet will not watch for


Can you explain this a bit more? If the content is a scrollable, won't it actually be watching for those drag gestures?

What this means is that unlike the non-scrolling version, a vertical drag gesture recognizer won't be placed over the whole sheet, and instead the vertical drags would be watched for by the scrolling content.

Except for things not part of the scrollable?

Piinks · 2025-12-08T23:21:07Z

packages/flutter/lib/src/cupertino/sheet.dart

+  ///
+  /// When this constructor is used, the content of the sheet will not watch for
+  /// drag gestures to trigger the drag downwards to dismiss behavior. Instead,
+  /// if a vertical happens within a scrollable widget that uses the [ScrollController]


I think a word is missing here.

I would focus this paragraph on the expected behavior. Some of the implementation details are not super relevant to the user.

Piinks · 2025-12-08T23:21:53Z

packages/flutter/lib/src/cupertino/sheet.dart

+  /// This example shows how to show a Cupertino Sheet with scrollable content,
+  /// and a navbar that will trigger the drag only on a gesture started within


Breadcrumbs would help here, what is the navbar?

chunhtai · 2025-12-09T23:38:02Z

but I think we'd need to have at least a scrollable boolean property in the constructor. When set to true it doesn't apply the drag gesture detector over the whole sheet.

Can you talk more about this? does this mean for non scrollable cupertino sheet user can start dragging anywhere in the sheet to start popping gesture? This sounds a bit unexpected.

Besides this I also + 1 to what justin suggested, Ideally if we can have a way to not passing controller from constructor, we don't need to change the API

MitchellGoodwin · 2025-12-09T23:42:48Z

Can you talk more about this? does this mean for non scrollable cupertino sheet user can start dragging anywhere in the sheet to start popping gesture? This sounds a bit unexpected.

Yes, that it is what it means, and that's how the native sheet works.

Screen.Recording.2025-12-09.at.3.41.55.PM.mov

You can disable that with the enableDrag in the constructor. Then with this PR you could re-enable it for, say just the navbar with the drag area class added in this PR.

chunhtai · 2025-12-09T23:40:54Z

packages/flutter/lib/src/cupertino/sheet.dart

+                    if (didPop) {
+                      return;
+                    }
+                    Navigator.of(context, rootNavigator: true).pop(result);


I know this is not introduced by this pr, but what if there is multiple navigator above the nested navigator? I thought we may want to pop just one level above this nested navigator

showCupertinoSheet always pushes to the root navigator, especially as it needs to slide the whole page down. So popping the sheet also targets the root navigator, as the last route in the stack should theoretically be the sheet you are meaning to pop, in the case of nested navigation.

If there is a situation where that does not work for their app, then we direct people to use CupertinoSheetRoute directly instead of showCupertinoSheet.

Ah ok, makes sense

Piinks · 2025-12-16T21:07:50Z

packages/flutter/lib/src/cupertino/sheet.dart

  WidgetBuilder? pageBuilder,
  WidgetBuilder? builder,


Just curious since I've been learning a bit more about this area, what is the difference between pageBuilder and builder?

Piinks · 2025-12-16T21:11:51Z

packages/flutter/lib/src/cupertino/sheet.dart

-    _dragGestureController!.dragUpdate(details.primaryDelta!, _stretchDragController!.controller);
+    _dragGestureController!.dragUpdate(
+      // Divide by size of the sheet.
+      details.primaryDelta! / sheetHeight,


Do we need to check for sheetHeight == 0?

Piinks · 2025-12-16T21:19:37Z

packages/flutter/lib/src/cupertino/sheet.dart

+  static VelocityTracker _cupertinoVelocityBuilder(PointerEvent event) =>
+      IOSScrollViewFlingVelocityTracker(event.kind);
+
+  double get sheetHeight => widget.sheetHeight ?? context.size!.height;


We should make sure the fallback is safe to access, has error message.

Piinks · 2025-12-16T21:20:45Z

packages/flutter/lib/src/cupertino/sheet.dart

      return;
    }
    _dragGestureController!.dragEnd(
-      details.velocity.pixelsPerSecond.dy / context.size!.height,


What about this change requires that sheet height has to be passed all the way down here instead of continuing to use context.size!.height?

Piinks

It would be best to update the design document about this change. In particular, some diagrams illustrating how gestures come in and are handled would be ideal. There are a lot of classes working together here, but it looks like there is some unfortunate leaking of information across boundaries we typically try to avoid. Updating the design document will help a lot with to see the whole picture here.

Piinks · 2025-12-16T21:31:03Z

packages/flutter/lib/src/cupertino/sheet.dart


  @override
  Widget buildContent(BuildContext context) {
+    final double sheetHeight =


There should probably be a call to debugCheckHasMediaQuery before accessing it.

Piinks · 2025-12-16T21:32:09Z

packages/flutter/lib/src/cupertino/sheet.dart

+  final double sheetHeight;
+
+  final CupertinoSheetRoute<dynamic> route;


Maybe something for the design doc to explain, if the CupertinoSheetRoute's role is to see if another sheet is in the tree already, why does it need the sheetHeight and the route itself?

Piinks · 2025-12-16T21:37:46Z

packages/flutter/lib/src/cupertino/sheet.dart

+  }
+}
+
+/// A scroll position that manages scroll activities for


These docs looks like leftover copy paste from the widgets class.
These should be updated to reflect the right context. To avoid confusion, it might be best to give this class a unique name.

Also something for the doc - since this was copied from the widgets layer and then changed to suit the use case, the document should talk about what is different and why.

github-actions bot added framework flutter/packages/flutter repository. See also f: labels. f: cupertino flutter/packages/flutter/cupertino repository labels Oct 21, 2025

MitchellGoodwin requested a review from Piinks October 21, 2025 20:16

Piinks reviewed Oct 22, 2025

View reviewed changes

MitchellGoodwin force-pushed the dragging-sheet branch from 7eae9f1 to f165a18 Compare November 21, 2025 17:00

Piinks reviewed Nov 25, 2025

View reviewed changes

chunhtai self-requested a review November 25, 2025 23:07

chunhtai reviewed Nov 26, 2025

View reviewed changes

MitchellGoodwin added 8 commits December 5, 2025 14:55

Add scrollableBuilder

8817960

Refactor

b3baddf

fix check for scrollcontroller

2dc2156

Partial refactor to DSS style

b37ddb9

Change extent to delta

a498867

refactor to no extent

c00a8b4

Remove changes to draggablescrollable

7d64cdc

Clean up

f1b984f

MitchellGoodwin added 6 commits December 5, 2025 14:57

Documentation

b1fa3e7

Pass height instead of context and fix typo

c547a6f

Tests

2bbd40a

Sample update and tests

aa989d3

Documentation

29bc426

Lints

b0d7ced

MitchellGoodwin force-pushed the dragging-sheet branch from 943dd41 to b0d7ced Compare December 5, 2025 23:00

MitchellGoodwin marked this pull request as ready for review December 5, 2025 23:01

MitchellGoodwin requested review from Piinks and chunhtai December 5, 2025 23:01

justinmc reviewed Dec 6, 2025

View reviewed changes

MitchellGoodwin added 2 commits December 8, 2025 10:09

Dispose scroll controller

5facacb

formatting

39ad4d3

Piinks reviewed Dec 8, 2025

View reviewed changes

Address review feedback

a9823b7

chunhtai reviewed Dec 9, 2025

View reviewed changes

Piinks reviewed Dec 16, 2025

View reviewed changes

		/// This example shows how to show a Cupertino Sheet with scrollable content,
		/// and a navbar that will trigger the drag only on a gesture started within

		final double sheetHeight;

		final CupertinoSheetRoute<dynamic> route;

CupertinoSheetRoute with scrolling and dragging #177337

Are you sure you want to change the base?

CupertinoSheetRoute with scrolling and dragging #177337

Conversation

MitchellGoodwin commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

lukepighetti commented Oct 21, 2025

Uh oh!

MitchellGoodwin commented Oct 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chunhtai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chunhtai commented Nov 26, 2025

Uh oh!

MitchellGoodwin commented Dec 1, 2025

Uh oh!

MitchellGoodwin commented Dec 1, 2025

Uh oh!

MitchellGoodwin commented Dec 2, 2025

Uh oh!

Piinks commented Dec 2, 2025

Uh oh!

MitchellGoodwin commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

justinmc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MitchellGoodwin commented Dec 6, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

MitchellGoodwin commented Oct 21, 2025 •

edited

Loading

MitchellGoodwin commented Dec 2, 2025 •

edited

Loading

MitchellGoodwin commented Dec 9, 2025 •

edited

Loading

Piinks Dec 16, 2025 •

edited

Loading