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

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

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.

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

Piinks · 2026-01-15T21:59:34Z

packages/flutter/lib/fix_data/fix_cupertino.yaml

      opacity:
        kind: 'fragment'
        value: 'arguments[0]'
+


Dropping comment to link to for reference.

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

github-actions bot added f: scrolling Viewports, list views, slivers, etc. d: api docs Issues with https://api.flutter.dev/ d: examples Sample code and demos and removed f: scrolling Viewports, list views, slivers, etc. labels Nov 21, 2025

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 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

Piinks reviewed Dec 8, 2025

View reviewed changes

packages/flutter/lib/src/cupertino/sheet.dart Outdated Show resolved Hide resolved

Piinks reviewed Dec 8, 2025

View reviewed changes

packages/flutter/lib/src/cupertino/sheet.dart Outdated Show resolved Hide resolved

MitchellGoodwin added 28 commits January 15, 2026 11:31

fix check for scrollcontroller

5098100

Partial refactor to DSS style

4121035

Change extent to delta

c5dc7c5

refactor to no extent

277b58a

Remove changes to draggablescrollable

ea3f636

Clean up

a3c9ff2

Drag Area and sample code

39a3743

Documentation

d763aba

Pass height instead of context and fix typo

449af70

Tests

42c67a2

Sample update and tests

5622bfc

Documentation

a633919

Lints

bad9832

Dispose scroll controller

14f07c2

formatting

5ffd7cd

Address review feedback

5174613

Refactor to one constructor

bf81e02

Remove sheetmode enum

4032bf0

Documentation adjustments, and deprecations in examples

2a5198b

Remove missed deprecated property

fb7d74d

Adjust tests for drag arena

55dc1c2

Remove reference to drag area

3e66501

Remove unused properties

f7de433

Review feedback

21cca95

Add dart fix

e1a1b77

Add dart fix

44b4eaa

Formatting

889ba4d

Rebase

5e792b0

MitchellGoodwin force-pushed the dragging-sheet branch from d735b89 to 5e792b0 Compare January 15, 2026 19:46

Piinks reviewed Jan 15, 2026

View reviewed changes

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!

Uh oh!

MitchellGoodwin commented Dec 6, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

MitchellGoodwin commented Oct 21, 2025 •

edited

Loading

MitchellGoodwin commented Dec 2, 2025 •

edited

Loading