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:

1. Backdrop Isolation — each glass layer manages its own GPU backdrop capture, preventing ghost artefacts when navigating between routes.

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

3. System Status Bar — optionally adjusts icon brightness to match your background via statusBarStyle. Automatically restores the previous style when the page is disposed.

4. Edge-to-Edge — optionally enables SystemUiMode.edgeToEdge so content draws behind the status and navigation bars. Restores the previous mode on dispose.

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

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

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(...),
)