From 1a86af3ff032a3c497ab7aa63cf41c251cbd22a8 Mon Sep 17 00:00:00 2001 From: Mitchell Goodwin <58190796+MitchellGoodwin@users.noreply.github.com> Date: Wed, 7 Jan 2026 15:43:58 -0800 Subject: [PATCH] Add drag handle to CupertinoSheet (#179962) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #179358. Adds the option to add a native styled drag handle to the top of a Cupertino sheet through the `showDragHandle` property. By default this is false, the same way it is for the native SwiftUI sheet. Styling for the handle is based off of native versions of the handle, and Apple's Figma files. From this PR: Screenshot 2025-12-16 at 12 53 06 PM From the iOS Maps app (this sheet has a slight transparency) Screenshot 2025-12-16 at 12 53 15 PM From the Figma files: Screenshot 2025-12-16 at 12 53 36 PM ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] 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](https://developers.google.com/gemini-code-assist/docs/review-github-code). 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. [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --- packages/flutter/lib/src/cupertino/sheet.dart | 63 ++++++++++- .../flutter/test/cupertino/sheet_test.dart | 103 ++++++++++++++++++ 2 files changed, 161 insertions(+), 5 deletions(-) diff --git a/packages/flutter/lib/src/cupertino/sheet.dart b/packages/flutter/lib/src/cupertino/sheet.dart index 79237ae512f..d1881ee9e32 100644 --- a/packages/flutter/lib/src/cupertino/sheet.dart +++ b/packages/flutter/lib/src/cupertino/sheet.dart @@ -124,6 +124,9 @@ final Animatable _kScaleTween = Tween(begin: 1.0, end: 1.0 - _kS /// means the sheet takes up only the bottom 10% of the screen. If not provided, defaults /// to 0.08 (8% of screen height). /// +/// When `showDragHandle` is set to `true`, then a drag handle will be placed at +/// the top of the sheet. This flag will default to false. +/// /// iOS sheet widgets are generally designed to be tightly coupled to the context /// of the widget that opened the sheet. As such, it is not recommended to push /// a non-sheet route that covers the sheet without first popping the sheet. If @@ -162,6 +165,7 @@ Future showCupertinoSheet({ bool useNestedNavigation = false, bool enableDrag = true, double? topGap, + bool showDragHandle = false, }) { assert(topGap == null || (topGap >= 0.0 && topGap <= 0.9), 'topGap must be between 0.0 and 0.9'); assert(pageBuilder != null || builder != null); @@ -203,10 +207,14 @@ Future showCupertinoSheet({ }; } - return Navigator.of( - context, - rootNavigator: true, - ).push(CupertinoSheetRoute(builder: widgetBuilder, enableDrag: enableDrag, topGap: topGap)); + return Navigator.of(context, rootNavigator: true).push( + CupertinoSheetRoute( + builder: widgetBuilder, + enableDrag: enableDrag, + showDragHandle: showDragHandle, + topGap: topGap, + ), + ); } /// Provides an iOS-style sheet transition. @@ -575,6 +583,7 @@ class CupertinoSheetRoute extends PageRoute with _CupertinoSheetRouteTrans required this.builder, this.enableDrag = true, double? topGap, + this.showDragHandle = false, }) : assert( topGap == null || (topGap >= 0.0 && topGap <= 0.9), 'topGap must be between 0.0 and 0.9', @@ -596,6 +605,50 @@ class CupertinoSheetRoute extends PageRoute with _CupertinoSheetRouteTrans @override bool get _hasCustomTopGap => _topGap != null; + /// Shows a drag handle at the top of the sheet. + /// + /// Defaults to false. + final bool showDragHandle; + + Widget _sheetWithDragHandle(BuildContext context) { + if (!showDragHandle) { + return builder(context); + } + + // Values derived from Apple's Figma files and a simulator running iOS 18.2. + const dragHandleTopPadding = 5.0; + const dragHandleHeight = 5.0; + const dragHandleWidth = 36.0; + const dragHandlePadding = 15.0; + + return Stack( + fit: StackFit.expand, + children: [ + MediaQuery( + data: MediaQuery.of( + context, + ).copyWith(padding: const EdgeInsets.only(top: dragHandlePadding)), + child: builder(context), + ), + const Align( + alignment: Alignment.topCenter, + child: Padding( + padding: EdgeInsetsGeometry.only(top: dragHandleTopPadding), + child: DecoratedBox( + decoration: ShapeDecoration( + shape: RoundedSuperellipseBorder( + borderRadius: BorderRadiusGeometry.all(Radius.circular(dragHandleWidth / 2)), + ), + color: CupertinoColors.tertiaryLabel, + ), + child: SizedBox(height: dragHandleHeight, width: dragHandleWidth), + ), + ), + ), + ], + ); + } + @override Widget buildContent(BuildContext context) { return MediaQuery.removePadding( @@ -605,7 +658,7 @@ class CupertinoSheetRoute extends PageRoute with _CupertinoSheetRouteTrans borderRadius: const BorderRadius.vertical(top: Radius.circular(12)), child: CupertinoUserInterfaceLevel( data: CupertinoUserInterfaceLevelData.elevated, - child: _CupertinoSheetScope(child: builder(context)), + child: _CupertinoSheetScope(child: _sheetWithDragHandle(context)), ), ), ); diff --git a/packages/flutter/test/cupertino/sheet_test.dart b/packages/flutter/test/cupertino/sheet_test.dart index 4819252bb95..c13bbd22e51 100644 --- a/packages/flutter/test/cupertino/sheet_test.dart +++ b/packages/flutter/test/cupertino/sheet_test.dart @@ -62,6 +62,109 @@ void main() { ); }); + testWidgets('showDragHandle adds a drag handle to the top of the sheet', ( + WidgetTester tester, + ) async { + final GlobalKey scaffoldKey = GlobalKey(); + + await tester.pumpWidget( + CupertinoApp( + home: CupertinoPageScaffold( + key: scaffoldKey, + child: Center( + child: Column( + children: [ + const Text('Page 1'), + CupertinoButton( + onPressed: () { + Navigator.push( + scaffoldKey.currentContext!, + CupertinoSheetRoute( + showDragHandle: true, + builder: (BuildContext context) { + return const CupertinoPageScaffold(child: Text('Page 2')); + }, + ), + ); + }, + child: const Text('Push Page 2'), + ), + ], + ), + ), + ), + ), + ); + + expect(find.text('Page 1'), findsOneWidget); + expect(find.text('Page 2'), findsNothing); + + await tester.tap(find.text('Push Page 2')); + await tester.pumpAndSettle(); + + expect(find.text('Page 2'), findsOneWidget); + final Finder dragHandleFinder = find.byWidgetPredicate((Widget widget) { + return widget is DecoratedBox && + widget.decoration is ShapeDecoration && + (widget.decoration as ShapeDecoration).color == CupertinoColors.tertiaryLabel; + }); + expect(dragHandleFinder, findsOneWidget); + }); + + testWidgets('showDragHandle adds a MediaQuery padding so content can render below the handle', ( + WidgetTester tester, + ) async { + final GlobalKey scaffoldKey = GlobalKey(); + + await tester.pumpWidget( + CupertinoApp( + home: CupertinoPageScaffold( + key: scaffoldKey, + child: Center( + child: Column( + children: [ + const Text('Page 1'), + CupertinoButton( + onPressed: () { + Navigator.push( + scaffoldKey.currentContext!, + CupertinoSheetRoute( + showDragHandle: true, + builder: (BuildContext context) { + return const CupertinoPageScaffold( + child: SafeArea(child: Text('Page 2')), + ); + }, + ), + ); + }, + child: const Text('Push Page 2'), + ), + ], + ), + ), + ), + ), + ); + + expect(find.text('Page 1'), findsOneWidget); + expect(find.text('Page 2'), findsNothing); + + await tester.tap(find.text('Push Page 2')); + await tester.pumpAndSettle(); + + expect(find.text('Page 2'), findsOneWidget); + final Finder dragHandleFinder = find.byWidgetPredicate((Widget widget) { + return widget is DecoratedBox && + widget.decoration is ShapeDecoration && + (widget.decoration as ShapeDecoration).color == CupertinoColors.tertiaryLabel; + }); + + final Offset dragHandleOffset = tester.getTopLeft(dragHandleFinder); + final Offset sheetContentOffset = tester.getTopLeft(find.text('Page 2')); + expect(sheetContentOffset.dy, greaterThan(dragHandleOffset.dy)); + }); + testWidgets('Previous route moves slight downward when sheet route is pushed', ( WidgetTester tester, ) async {