showCupertinoSheet<T> function

Future<T?> showCupertinoSheet<T>({
  1. required BuildContext context,
  2. required WidgetBuilder pageBuilder,
  3. bool useNestedNavigation = false,
})

Shows a Cupertino-style sheet widget that slides up from the bottom of the screen and stacks the previous route behind the new sheet.

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.

useNestedNavigation allows new routes to be pushed inside of a CupertinoSheetRoute by adding a new Navigator inside of the CupertinoSheetRoute.

When useNestedNavigation is set to true, any route pushed to the stack from within the context of the CupertinoSheetRoute will display within that sheet. System back gestures and programatic pops on the initial route in a sheet will also be intercepted to pop the whole CupertinoSheetRoute. If a custom Navigator setup is needed, like for example to enable named routes or the pages API, then it is recommended to directly push a CupertinoSheetRoute to the stack with whatever configuration needed. See CupertinoSheetRoute for an example that manually sets up nested navigation.

The whole sheet can be popped at once by either dragging down on the sheet, or calling CupertinoSheetRoute.popSheet.

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 necessary however, it can be done by pushing to the root Navigator.

If useNestedNavigation is false (the default), then a CupertinoSheetRoute will be shown with no Navigator widget. Multiple calls to showCupertinoSheet can still be made to show multiple stacked sheets, if desired.

showCupertinoSheet always pushes the CupertinoSheetRoute to the root Navigator. This is to ensure the previous route animates correctly.

Returns a Future that resolves to the value (if any) that was passed to Navigator.pop when the sheet was closed.

This example shows how to navigate to use showCupertinoSheet to display a Cupertino sheet widget with nested navigation.
link

To create a local project with this code sample, run:
flutter create --sample=cupertino.showCupertinoSheet.1 mysample

See also:

Implementation

Future<T?> showCupertinoSheet<T>({
  required BuildContext context,
  required WidgetBuilder pageBuilder,
  bool useNestedNavigation = false,
}) {
  final WidgetBuilder builder;
  final GlobalKey<NavigatorState> nestedNavigatorKey = GlobalKey<NavigatorState>();
  if (!useNestedNavigation) {
    builder = pageBuilder;
  } else {
    builder = (BuildContext context) {
      return NavigatorPopHandler(
        onPopWithResult: (T? result) {
          nestedNavigatorKey.currentState!.maybePop();
        },
        child: Navigator(
          key: nestedNavigatorKey,
          initialRoute: '/',
          onGenerateInitialRoutes: (NavigatorState navigator, String initialRouteName) {
            return <Route<void>>[
              CupertinoPageRoute<void>(
                builder: (BuildContext context) {
                  return PopScope(
                    canPop: false,
                    onPopInvokedWithResult: (bool didPop, Object? result) {
                      if (didPop) {
                        return;
                      }
                      Navigator.of(context, rootNavigator: true).pop(result);
                    },
                    child: pageBuilder(context),
                  );
                },
              ),
            ];
          },
        ),
      );
    };
  }

  return Navigator.of(
    context,
    rootNavigator: true,
  ).push<T>(CupertinoSheetRoute<T>(builder: builder));
}