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

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.

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

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

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

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

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

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

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.

Steps to reproduce
Create a CupertinoSheetRoute with a ListView.separated inside
Open the sheet
Scroll the ListView to the very top
Try to drag down from the list area to dismiss the sheet
The sheet does not dismiss
Expected: When the ListView is at the top and user drags down, the sheet should dismiss (like native iOS behavior)
Actual: The sheet stays open and does not respond to the downward drag gesture

Expected results
When the ListView is scrolled to the top and the user continues to drag downward, the CupertinoSheetRoute should begin its dismiss animation and close, similar to native iOS sheet behavior.

Actual results
The sheet does not dismiss when dragging down on the ListView area. The drag gesture is consumed by the ListView and never passed to the sheet's drag-to-dismiss handler.

Note: PR #177337 (merged Jan 23, 2026) was supposed to fix this issue (#161687), but the problem persists on stable 3.41.2.

Uploading FILE 2026-02-25 16:14:58.mp4…

import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
const MyApp({super.key});

@OverRide
Widget build(BuildContext context) {
return MaterialApp(debugShowCheckedModeBanner: false, home: HomePage());
}
}

class HomePage extends StatelessWidget {
const HomePage({super.key});

@OverRide
Widget build(BuildContext context) {
return CupertinoPageScaffold(
navigationBar: const CupertinoNavigationBar(middle: Text('Home')),
child: SafeArea(
child: Center(
child: CupertinoButton.filled(
child: const Text('Open Cupertino Sheet'),
onPressed: () {
showCupertinoSheet(
context: context,
builder: (BuildContext sheetContext) {
return const _MySheetPage();
},
enableDrag: true,
showDragHandle: false,
useNestedNavigation: true,
);
},
),
),
),
);
}
}

class _MySheetPage extends StatefulWidget {
const _MySheetPage();

@OverRide
State<_MySheetPage> createState() => _MySheetPageState();
}

class _MySheetPageState extends State<_MySheetPage> {
@OverRide
Widget build(BuildContext context) {
return CupertinoPageScaffold(
navigationBar: CupertinoNavigationBar(
middle: const Text('Sheet'),
trailing: CupertinoButton(
padding: EdgeInsets.zero,
onPressed: () => Navigator.of(context).maybePop(),
child: const Text('Close'),
),
),
child: SafeArea(
top: false,
child: Column(
children: [
const SizedBox(height: 8),
const _GrabHandle(),
const SizedBox(height: 8),

        Expanded(
          child: ListView.separated(
            physics: const AlwaysScrollableScrollPhysics(
              parent: BouncingScrollPhysics(),
            ),
            padding: const EdgeInsets.fromLTRB(16, 12, 16, 24),
            itemCount: 60,
            separatorBuilder: (_, _) => const SizedBox(height: 10),
            itemBuilder: (context, index) {
              return _CupertinoCard(
                title: 'Item #$index',
                subtitle: 'info',
              );
            },
          ),
        ),
      ],
    ),
  ),
);

}
}

class _GrabHandle extends StatelessWidget {
const _GrabHandle();

@OverRide
Widget build(BuildContext context) {
return Center(
child: Container(
width: 44,
height: 5,
decoration: BoxDecoration(
color: CupertinoColors.systemGrey4,
borderRadius: BorderRadius.circular(99),
),
),
);
}
}

class _CupertinoCard extends StatelessWidget {
final String title;
final String subtitle;

const _CupertinoCard({required this.title, required this.subtitle});

@OverRide
Widget build(BuildContext context) {
return Material(
child: DecoratedBox(
decoration: BoxDecoration(
color: CupertinoColors.secondarySystemBackground,
borderRadius: BorderRadius.circular(14),
),
child: Padding(
padding: const EdgeInsets.all(14),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
title,
style: const TextStyle(
fontSize: 17,
fontWeight: FontWeight.w600,
),
),
const SizedBox(height: 6),
Text(
subtitle,
style: const TextStyle(
fontSize: 14,
color: CupertinoColors.systemGrey,
),
),
const SizedBox(height: 10),
CupertinoButton(
padding: const EdgeInsets.symmetric(
horizontal: 10,
vertical: 6,
),
onPressed: () {},
child: const Text('Action'),
),
],
),
),
),
);
}
}