Skip to main content

​
Overview

TransparentRoute and TransparentPage provide transparent page routes that allow underlying content to remain visible. This is useful for overlays, modals, or dialogs that should not completely obscure the content beneath them.

​
TransparentPage

A page that creates a transparent route when used with Navigator 2.

​
Constructor

const TransparentPage({
  Key? key,
  String? name,
  Object? arguments,
  String? restorationId,
  required Widget child,
  bool maintainState = true,
  bool fullscreenDialog = false,
  Color barrierColor = Colors.transparent,
})
​
child
Widget
required
The content to be shown in the route created by this page.
​
maintainState
bool
default:"true"
Whether to maintain the state of the route when it’s not visible.
​
fullscreenDialog
bool
default:"false"
Whether this page should be treated as a fullscreen dialog.
​
barrierColor
Color
default:"Colors.transparent"
The color of the barrier that blocks interaction with routes below.

​
Usage with NavigationData

NavigationData(
  label: 'overlay',
  url: '/overlay',
  pageBuilder: ({key, name, child, routeData, globalData, arguments}) {
    return TransparentPage(
      key: key,
      name: name,
      child: child,
      barrierColor: Colors.black.withOpacity(0.5),
    );
  },
  builder: (context, routeData, globalData) => MyOverlayWidget(),
)

​
TransparentRoute

A programmatic transparent route for use with Navigator 1 API or custom navigation.

​
Constructor

TransparentRoute({
  RouteSettings? settings,
  bool? fullscreenDialog,
  required WidgetBuilder builder,
  bool maintainState = true,
  RouteTransitionsBuilder transitionsBuilder = _defaultTransitionsBuilder,
  Color barrierColor = Colors.transparent,
})
​
builder
WidgetBuilder
required
Builder function for the route’s widget.
​
maintainState
bool
default:"true"
Whether to maintain the state of the route when it’s not visible.
​
transitionsBuilder
RouteTransitionsBuilder
Builder function for custom route transitions. Defaults to a simple fade transition.
​
barrierColor
Color
default:"Colors.transparent"
The color of the barrier that blocks interaction with routes below.

​
Direct usage

Navigator.of(context).push(
  TransparentRoute(
    builder: (context) => MyOverlayContent(),
    barrierColor: Colors.black.withOpacity(0.3),
  ),
);

​
FadeUpwardsPageTransition

The transparent routes use a custom fade upwards transition that preserves the appearance of underlying routes. 
FadeUpwardsPageTransition({
  required Animation<double> routeAnimation,
  required Widget child,
})
This transition:
  • Fades in the new route with an ease-in curve
  • Slides the content upwards from 1/4 screen below
  • Ensures underlying content remains visible and stationary

​
Key features

Non-opaque routes

Routes are not opaque, allowing content underneath to show through

Custom barrier colors

Configure barrier color and opacity for different overlay effects

Preserved animations

Custom transitions prevent unwanted animations on underlying routes

Accessibility support

Includes proper Semantics for screen readers

​
Common use cases

TransparentPage(
  child: Center(
    child: Card(
      child: Padding(
        padding: EdgeInsets.all(24),
        child: MyModalContent(),
      ),
    ),
  ),
  barrierColor: Colors.black.withOpacity(0.5),
)

​
Bottom sheets

TransparentPage(
  child: Align(
    alignment: Alignment.bottomCenter,
    child: MyBottomSheet(),
  ),
  barrierColor: Colors.black.withOpacity(0.3),
)

​
Floating dialogs

TransparentPage(
  child: Dialog(
    child: MyDialogContent(),
  ),
  barrierColor: Colors.black.withOpacity(0.6),
)
Transparent routes override default Android OpenUpwardsPageTransition and iOS CupertinoSlideTransition to ensure the route below stays stationary and visible.
Use barrierColor with partial opacity to create dimmed backgrounds that draw attention to the overlay while keeping underlying content visible.

Build docs developers (and LLMs) love

Get started for freeTalk to us