liquid_glass_bridge

A cross-platform Flutter package that gives you one API for liquid-glass UI.

iOS: native Swift/UIKit renderer (UIVisualEffectView) for system-like frosted material.
Android/Web/Desktop: Flutter renderer (BackdropFilter + tint + border + highlight + optional noise).
Lens mode: shader overlay with automatic fallback.

Install

flutter pub add liquid_glass_bridge

Platform Setup (iOS and Android)

liquid_glass_bridge is auto-wired by Flutter plugins, but apps should verify these minimum platform settings:

iOS

Set iOS deployment target to 13.0 or newer.

# ios/Podfile
platform :ios, '13.0'

Refresh CocoaPods after changing deployment targets:

cd ios && pod install

Use LiquidGlassMode.auto (recommended) or LiquidGlassMode.iosNative to force UIKit rendering.
No extra iOS permissions are required.

Android

Set Android minimum SDK to 21 or newer in your app module.

// android/app/build.gradle
defaultConfig {
    minSdkVersion 21
}

Use LiquidGlassMode.auto (recommended) or LiquidGlassMode.androidNative to force the native Android blur view.
No extra Android permissions are required.

If your Gradle setup cannot resolve BlurView, add JitPack to repositories:

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

Included Widgets

LiquidGlassSurface
LiquidGlassButton
LiquidGlassNavigationBar
LiquidGlassBottomNavigationBar

Modes and Quality

`LiquidGlassMode`

auto: iOS -> native UIKit, Android -> native blur view, others -> Flutter glass
iosNative: iOS native, others fallback to Flutter glass
androidNative: Android native blur, others fallback to Flutter glass
flutterGlass: force Flutter glass everywhere
flutterLens: force lens shader (falls back to glass when unavailable)

`LiquidGlassQuality`

low: better performance
medium: balanced (default)
high: stronger effect, higher cost

Main Surface API

LiquidGlassSurface parameters:

child
borderRadius
padding, margin
elevation
tintColor, tintOpacity
blurSigma
borderColor, borderWidth
highlightStrength
noiseOpacity
iosBlurStyle
style, platformStyle
mode
quality
enabled
debugLabel

Usage

Surface

LiquidGlassSurface(
  mode: LiquidGlassMode.auto,
  quality: LiquidGlassQuality.medium,
  borderRadius: BorderRadius.circular(24),
  blurSigma: 18,
  noiseOpacity: 0.05,
  child: const Text('Liquid glass'),
)

Styles and Presets

Use LiquidGlassStyle for reusable visual settings. When style or platformStyle is provided, those values override the per-parameter defaults.

final LiquidGlassStyle style = LiquidGlassPresets.frosted;

LiquidGlassSurface(
  style: style,
  child: const Text('Reusable style'),
)

Theming

You can set app-wide defaults with LiquidGlassTheme. When a theme is present, widgets will prefer its style/platformStyle and default mode/quality. Per-widget overrides should use style or platformStyle.

LiquidGlassTheme(
  data: LiquidGlassThemeData(
    style: LiquidGlassPresets.frosted,
    mode: LiquidGlassMode.auto,
    quality: LiquidGlassQuality.medium,
  ),
  child: MaterialApp(
    home: const ExampleScreen(),
  ),
)

Platform-specific overrides:

final LiquidGlassPlatformStyle platformStyle = LiquidGlassPlatformStyle(
  fallback: LiquidGlassPresets.frosted,
  ios: LiquidGlassPresets.thin.copyWith(
    iosBlurStyle: LiquidGlassIosBlurStyle.systemThinMaterial,
  ),
  android: LiquidGlassPresets.dense.copyWith(blurSigma: 22),
);

LiquidGlassSurface(
  platformStyle: platformStyle,
  child: const Text('Per-platform glass'),
)

Scaffold(
  appBar: const LiquidGlassNavigationBar(
    title: Text('Home'),
  ),
  bottomNavigationBar: LiquidGlassBottomNavigationBar(
    items: const <LiquidGlassNavItem>[
      LiquidGlassNavItem(icon: Icons.home_outlined, label: 'Home'),
      LiquidGlassNavItem(icon: Icons.search_outlined, label: 'Search'),
    ],
    currentIndex: 0,
    onTap: (int index) {},
  ),
  body: Center(
    child: LiquidGlassButton(
      onPressed: () {},
      child: const Text('Continue'),
    ),
  ),
)

iOS Native Rendering Notes

On iOS, auto and iosNative use a platform view backed by Swift/UIKit:

native blur material (UIVisualEffectView)
native tint/border/highlight composition
Flutter child content remains in Dart above the native layer
blurSigma is ignored for native iOS; use iosBlurStyle instead

On Android, auto and androidNative use a platform view backed by a native blur view. If you need to force the Flutter renderer, set mode to flutterGlass.

Note: Android native blur uses the BlurView library under the hood.

Performance Tips (Android/Flutter renderer)

Keep blurSigma moderate (12-18 is a good start).
Use LiquidGlassQuality.low for long scrolling lists.
Keep noiseOpacity subtle (0.02-0.06).
Avoid many overlapping large blurred surfaces.

Example App

Run from package root:

flutter run -d <device> -t example/lib/main.dart

or from example/:

flutter run

License

MIT