GlassPage class

The recommended root widget for building a route or screen with glass surfaces.

GlassPage eliminates the boilerplate required to set up a correct, performant glass UI on any route. In a single widget it handles:

Transparent Scaffold — forces the Scaffold's default background colour to transparent via a Theme override, so your background shows through without any extra configuration.
Ghosting Prevention — wraps the route in a GlassBackdropScope to isolate this route's GPU backdrop from adjacent routes during navigation transitions, preventing visual artefacts.
Background Scope — wraps the route in a LiquidGlassScope so that GlassBackgroundSource can locate the capture key when enableBackgroundSampling is true. Required for real colour absorption.
System Status Bar — optionally adjusts icon brightness to match your background via statusBarStyle. Automatically restores the previous style when the page is disposed.
Edge-to-Edge — optionally enables SystemUiMode.edgeToEdge so content draws behind the status and navigation bars. Restores the previous mode on dispose.
Per-Page Theme Override — optionally wraps the subtree in a scoped GlassTheme via themeOverride, letting individual screens break from the app-wide glass theme (e.g. a more dramatic onboarding or paywall screen). Widget-level settings parameters still take precedence.
Setup Guard (debug only) — emits a FlutterError in debug mode if LiquidGlassWidgets.initialize was never called, with a direct link to the correct setup pattern.

Performance characteristics

State	Cost
`enableBackgroundSampling: false` (default)	Near-zero — one GlobalKey allocation, no Ticker
Adaptive quality degraded to GlassQuality.minimal	Near-zero — sampling automatically disabled
Sampling active, static background	Very low — Ticker fires, detects no change after first capture
Sampling active, animated background	Normal — Ticker captures on size/position changes

Recommended setup

App root (once):

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await LiquidGlassWidgets.initialize();
  runApp(LiquidGlassWidgets.wrap(child: MyApp(), adaptiveQuality: true));
}

Typical screen (zero boilerplate):

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return GlassPage(
      background: Image.asset('assets/wallpaper.jpg', fit: BoxFit.cover),
      child: Scaffold(
        appBar: GlassAppBar(title: const Text('Home')),
        body: MyContent(),
      ),
    );
  }
}

Edge-to-edge wallpaper screen with status bar styling:

GlassPage(
  background: Image.asset('assets/wallpaper.jpg', fit: BoxFit.cover),
  edgeToEdge: true,
  statusBarStyle: GlassStatusBarStyle.auto,
  child: Scaffold(...),
)

Special page with a custom glass intensity:

GlassPage(
  background: myGradient,
  themeOverride: GlassThemeData(
    light: GlassThemeVariant(
      settings: GlassThemeSettings(blur: 2, glowIntensity: 0.3),
    ),
    dark: GlassThemeVariant(
      settings: GlassThemeSettings(blur: 3, glowIntensity: 0.5),
    ),
  ),
  child: Scaffold(...),
)

Pure frosted look (no wallpaper, no sampling):

GlassPage(
  background: Container(color: Colors.black),
  child: Scaffold(...),
)

Inheritance

Constructors

GlassPage({Key? key, Widget? background, required Widget child, bool? enableBackgroundSampling, GlassStatusBarStyle statusBarStyle = GlassStatusBarStyle.none, bool edgeToEdge = false, GlassThemeData? themeOverride}): Creates a GlassPage.
const

Properties

background → Widget?: The background widget (e.g. an Image or gradient Container) that sits behind the app content and, optionally, provides colours for glass to absorb.
final
child → Widget: The main content of the screen, typically a Scaffold.
final
edgeToEdge → bool: Whether to enable edge-to-edge rendering on this screen.
final
enableBackgroundSampling → bool?: Whether to capture the background as a GPU texture for glass colour absorption.
final
hashCode → int: The hash code for this object.
no setterinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
statusBarStyle → GlassStatusBarStyle: How to style the system status bar icons on this screen.
final
themeOverride → GlassThemeData?: An optional per-page GlassThemeData that overrides the app-level GlassTheme for all glass widgets within this screen.
final

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<GlassPage>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited