# Liquid Glass Widgets Bring Apple's Liquid Glass to your Flutter app — from the iOS 26 original to the iOS 27 material — with real shader-based blur, physics-driven jelly animations, and dynamic lighting across every platform. [](https://pub.dev/packages/liquid_glass_widgets) [](https://pub.dev/packages/liquid_glass_widgets/score) [](https://pub.dev/packages/liquid_glass_widgets/score) [](https://github.com/sdegenaar/liquid_glass_widgets/actions/workflows/ci.yml) [](https://codecov.io/gh/sdegenaar/liquid_glass_widgets) [](https://opensource.org/licenses/MIT)

Installation

dependencies:
  liquid_glass_widgets: ^1.16.0

flutter pub get

Flutter version requirement: Requires Flutter ≥ 3.41.0 (Dart ≥ 3.5.0). Recommended: Flutter 3.41+ for the best Impeller rendering quality. This package uses cutting-edge shader APIs that improve significantly with each Flutter release.

Quick Start

Two steps — that's the entire setup:

Step 1. Call initialize() in main() to pre-warm shaders.

Step 2. Wrap your app with LiquidGlassWidgets.wrap():

import 'package:flutter/material.dart';
import 'package:liquid_glass_widgets/liquid_glass_widgets.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await LiquidGlassWidgets.initialize();

  runApp(LiquidGlassWidgets.wrap(child: const MyApp()));
}

initialize() performs 100% non-blocking async disk-to-RAM I/O — zero GPU draw calls, zero rasterization — so the OS window always presents immediately. On Android, iOS, and macOS, all premium shaders are preloaded at startup for instant Frame 1 rendering. Advanced control:

// Default: automatically preloads all shaders on Android, iOS, macOS;
// skips unused premium shaders on Windows, Linux, and Web.
await LiquidGlassWidgets.initialize();

// Advanced: override the preloading strategy.
await LiquidGlassWidgets.initialize(
  warmUpMode: GlassWarmUpMode.auto,   // default — smart per-platform preload
  // warmUpMode: GlassWarmUpMode.always, // force all shaders on all platforms
  // warmUpMode: GlassWarmUpMode.never,  // skip heavy shader preload entirely
  enablePerformanceMonitor: false,    // suppress debug raster monitor (default: true)
);

Using MaterialApp? Add one line so glass widgets honour your ThemeMode instead of the raw OS brightness: dart runApp(LiquidGlassWidgets.wrap( child: const MyApp(), brightnessResolver: Theme.maybeBrightnessOf, // ← required for MaterialApp )); Without this, shadows and borders can disappear when the device is in Dark Mode even if your app is set to Light Mode (and vice-versa). CupertinoApp users can omit it.

That's it. Then use GlassScaffold on each screen — it handles background, status bar, z-ordering, and edge fading automatically:

GlassScaffold(
  background: Image.asset('assets/wallpaper.jpg', fit: BoxFit.cover),
  statusBarStyle: GlassStatusBarStyle.auto,
  appBar: GlassAppBar(title: const Text('My App')),
  body: Center(child: GlassContainer.card(child: Text('Hello, Glass!'))),
)

Why GlassScaffold? Glass effects refract and blur against whatever is behind them. Without a controlled background, glass surfaces can appear flat, incorrectly tinted, or invisible. GlassScaffold wires up the background source, glass rendering layer, and bar isolation automatically — one widget instead of five.

Accessibility is on by default. The library automatically reads the device's Reduce Motion setting and approximates Reduce Transparency via the Increase Contrast signal — no extra setup required. See Accessibility for details.

Choose the right widget

The package is centred around navigation chrome — GlassScaffold with GlassAppBar and GlassTabBar is the primary pattern and where the iOS 26 liquid glass effect is most impactful.

GlassContainer / GlassContainer.card are fully supported for localised glass UI (floating panels, settings cards, etc.) but most screens should start with GlassScaffold.

Optional: quality & theming

For production apps, pass adaptiveQuality and/or theme to wrap() at the same call site:

runApp(LiquidGlassWidgets.wrap(
  child: const MyApp(),
  brightnessResolver: Theme.maybeBrightnessOf, // MaterialApp users: required
  adaptiveQuality: true,          // auto-benchmarks device, degrades gracefully
  theme: GlassThemeData.simple(   // optional app-wide glass defaults
    blur: 10,
    thickness: 30,
    quality: GlassQuality.standard,
  ),
));

Both parameters are optional — omit them and the library uses sensible defaults.

AI Coding & Vibecoding Support

Building with Cursor, Claude Code, Antigravity, or GitHub Copilot? AI models frequently hallucinate obsolete APIs or write manual BackdropFilter stacks instead of using the official Liquid Glass component suite.

Teach your AI agent the exact API patterns and architectural rules:

• Antigravity / Gemini CLI: Install the official skill into your project: bash mkdir -p .agents/skills/liquid-glass-widgets curl -sSL https://raw.githubusercontent.com/sdegenaar/liquid_glass_widgets/main/skills/liquid-glass-widgets/SKILL.md -o .agents/skills/liquid-glass-widgets/SKILL.md
• Cursor: Copy skills/liquid-glass-widgets/SKILL.md to .cursor/rules/liquid-glass.mdc in your project.
• Claude Code: Add to .claude/skills/liquid-glass-widgets/SKILL.md or copy rules into your project's CLAUDE.md.
• Details & Other IDEs: See skills/README.md.

Features

• Comprehensive glass widget library — containers, interactive controls, inputs, feedback, overlays, and navigation surfaces (see Widget Categories)
• iOS 27 parity — the LiquidGlassSettings.ios27Light / ios27Dark material (drawn in full on premium, approximated on standard and web), GlassThemeData.ios27() as a one-line app-wide preset, pinned navigation chrome that morphs between routes under GlassNavigationShell, GlassBarItem.spacer() capsule splits that bud and merge like ToolbarSpacer(.fixed), and iPhone Duo's vertical bar strip. See docs/GLASS_NAVIGATION_TRANSITION.md
• Native list & navigation patterns — swipe actions, edit mode with drag-to-reorder, disclosure groups, context menus, full-screen covers, date pickers and a declarative GlassNavigationStack, modeled on their SwiftUI counterparts. Pair with GlassSurfaceStyle.solid for flat inset-grouped cards
• Liquid Morph Engine — a standalone physics system powering iOS 26-style liquid morphing. GlassMenu morphs out of its trigger button, and GlassModalSheet.show(morphFrom:) presents a modal sheet out of a GlassMorphTrigger the same way — the trigger empties, a glass droplet inflates as it travels, and dismissing pours it back. See docs/LIQUID_MORPH_ENGINE.md
• Real frosted glass — native two-pass Gaussian blur + shader refraction on Impeller; lightweight shader on Skia/Web
• Just works everywhere — iOS, Android, macOS, Web, Windows, Linux; rendering path chosen automatically
• Adaptive quality (experimental) — GlassAdaptiveScope benchmarks the device at startup and adjusts quality in real time: minimal on slow hardware, standard on mid-range, premium on fast devices. Degrades on thermal throttle, recovers when cool
• Zero external pubspec.yaml dependencies — pure Flutter SDK with custom GLSL shaders; rendering pipeline and spring utilities built on vendored open-source work (see Dependencies)
• One-line setup — LiquidGlassWidgets.wrap(child: myApp) handles accessibility bridging, adaptive quality, and global theming; use GlassScaffold per screen for automatic backdrop isolation, z-ordering, edge fading, and status bar styling
• Content-aware brightness — glass bars automatically flip between light and dark icons/labels based on the content scrolling behind them. One flag on GlassScaffold, matches iOS 26 behaviour
• Gyroscope lighting — GlassMotionScope drives specular highlights from any Stream<double>
• WCAG-compliant by default — Reduce Motion is respected automatically. Reduce Transparency is approximated via the Increase Contrast signal (see Accessibility)
• Full keyboard & screen reader support — every interactive widget supports Tab navigation, Space/Enter activation, and VoiceOver/TalkBack semantics out of the box; focus is visualised with an iOS 26-style outset ring
• Full RTL (Right-to-Left) support — layouts, drag directions, tab ordering, and physics auto-reverse for Arabic, Hebrew, and Persian

Glass vs Content — Design Philosophy

In iOS 26, glass is reserved for the navigation and control layer — the floating UI that sits above your app's content. Content areas (lists, cards, article tiles) stay opaque.