g1455 library Getting started

Liquid Glass for Flutter: refraction, blur, tint and a rim over the live backdrop, in the shape the engine already draws.

One GlassHost captures what is under all of its glass, once, and only when something there changed; every surface below it samples that capture. Every name here is live on the site, with a guide and a demo: g1455.plugfox.dev.

MaterialApp(
  // Above the navigator: dialogs, sheets and menus are under it too.
  builder: (BuildContext context, Widget? navigator) => GlassHost(
    richBackdrop: true,
    minLabelContrast: kTextContrastAA,
    child: navigator!,
  ),
  home: const Scaffold(
    body: Center(child: GlassBar(child: Text('Hello, glass'))),
  ),
)

The parts

Topic What is in it
Foundations GlassHost, GlassSurface, GlassFinish, GlassTheme, GlassRipple, GlassAdaptive, GlassPress, GlassConcentric
Panels and controls GlassBar, GlassButton, GlassCard, GlassSwitch, GlassSlider, GlassTabBar, GlassSegmentedControl, GlassButtonGroup, GlassTextField, GlassSearchBar, GlassStepper, GlassPageControl, GlassBadge, GlassScrollEdge, GlassScaffold
Modals showGlassDialog, GlassAlert, showGlassSheet, GlassSheetDetent, GlassMenuAnchor, GlassPopoverAnchor
Composition GlassGroup, GlassTravel, GlassMorph, GlassAbove
Capture control GlassProxy, GlassProxyPainter, GlassBackdrop
Cost and policy GlassTierPolicy, GlassLedger, GlassHardware, GlassThermalState

Each topic has a page of its own in the sidebar, with an overview and examples.

What is exported, and what is not

Nothing here is stable yet: the API is 0.x and every change is in the changelog. What is exported is what an application has to declare, because the render tree does not carry it — plus the two ledgers that turn those declarations into numbers somebody measured. The seams a benchmark turns are in package:g1455/glass_diagnostics.dart, not here.

Classes

GlassAbove Composition
Raises every glass surface below it lift levels above the glass beside it.
GlassAdaptive Foundations
How a GlassHost's glass reads its own backdrop: pass one as GlassHost.adaptive to turn it on.
GlassAlert Modals
iOS 26's alert, on glass.
GlassAlertAction Modals
One button of a GlassAlert.
GlassBackdrop Capture control
Declares what is behind the glass in child, so that glass samples the declaration instead of a capture of the screen.
GlassBackdropDeclaration Capture control
What a GlassBackdrop declared, as the surfaces below it read it.
GlassBackdropReading Foundations
What one glass read of the backdrop under it: the mean of the captured pixels inside its box.
GlassBadge Panels and controls
A count or a dot on the corner of child — an opaque red capsule, not glass, as iOS 26 draws a badge.
GlassBar Panels and controls
A glass bar: the navigation layer, which is where Apple's guidelines put this material.
GlassBlendGroup Composition
The membership of one blend group.
GlassButton Panels and controls
A glass control: a capsule that takes a tap and brightens while held.
GlassButtonGroup Panels and controls
Adjacent actions in one glass capsule — a circle for one — as iOS 26's toolbar draws them. One surface whatever the count.
GlassCard Panels and controls
A glass card: the same panel as GlassBar with a corner instead of a capsule.
GlassConcentric Foundations
Radii concentric with a container's: the container's radius less the inset between the two, never below a floor.
GlassDropMotion Foundations
How a held drop deforms as it moves: stretched along its travel while it speeds up, squashed while it slows down, round at a constant speed.
GlassDropStretch Foundations
The deformation of one drop, fed where the drop is once a frame.
GlassDropStretchDriver Foundations
Runs a GlassDropStretch off a ticker while its drop moves, and says when the deformation changed. The package's controls' half of the mechanism.
GlassFade Foundations
A fade across a glass surface: whole at begin, gone at end, a smoothstep between — in the surface's own logical coordinates.
GlassFinish Foundations
What the glass does to the light it lets through: how much it blurs and how much of it survives.
GlassGroup Composition
Draws every GlassSurface below it as one fused shape.
GlassGroupScope Composition
Carries the group down to the surfaces inside it.
GlassHost Foundations
Owns the whole proxy pipeline for one screen: it captures what is painted under the glass and hands it to every GlassSurface below it.
GlassLedger Cost and policy
The register of glass surfaces on one screen.
GlassLegibility Foundations
What a surface under a theme actually draws: the finish after any dim, the label colour, and the outline under increase contrast.
GlassLoad Cost and policy
What the register says, read against one platform's measurements.
GlassMenuAnchor Modals
A glass menu that grows out of builder's anchor, in the nearest Overlay, which has to be under the GlassHost.
GlassMenuController Modals
What a GlassMenuAnchor's or a GlassPopoverAnchor's builder is given to open and close what it anchors.
GlassMenuItem Modals
One row of a GlassMenuAnchor's menu, at least kGlassMenuRowHeight tall and taller for a label of more lines.
GlassMorph Composition
A piece of glass that flows to the size of whatever child it is given.
GlassMorphMotion Composition
How a GlassMorph moves: a spring, by its perceptual duration and bounce.
GlassOptics Foundations
The shape of the refraction: how far in it reaches, how hard it bends, and how it falls off.
GlassPageControl Panels and controls
Page dots on a glass capsule — iOS's UIPageControl on its platter.
GlassPopoverAnchor Modals
A glass panel of any content that grows out of builder's anchor, as GlassMenuAnchor's menu does, and stays open until a tap outside it or GlassMenuController.close — a popover, for content that is changed in place rather than chosen once.
GlassPress Foundations
How a pressed glass control responds: it grows by grow while held, and leans up to maxPull toward a finger that drags, stretched up to maxStretch along the drag and squashed across it.
GlassProxy Capture control
Declares what its subtree is in the glass proxy.
GlassProxyPainter Capture control
Draws a stand-in for a subtree in the proxy, for GlassProxy.replace.
GlassRipple Foundations
How a glass surface answers a touch with a wave.
GlassScaffold Panels and controls
A screen: a body that scrolls under a glass topBar, with an optional bottomBar and floatingAction, under a GlassHost.
GlassScope Cost and policy
Carries one GlassLedger down the tree.
GlassScrollEdge Panels and controls
The scroll edge effect under a bar, and the bar.
GlassSearchBar Panels and controls
A search field in a glass capsule, with a clear button while there is text and a Cancel button that slides in beside it while it has the focus.
GlassSegmentedControl Panels and controls
A row of mutually exclusive segments; the selected one lifts into a clear glass drop while a finger is on it. See the file comment for what it costs.
GlassSlider Panels and controls
A slider whose knob becomes a clear glass drop while it is held.
GlassStepper Panels and controls
A minus and a plus in one glass capsule, stepping a number between min and max — iOS's UIStepper.
GlassSurface Foundations
Declares a region of the screen as glass.
GlassSurfaceCluster Cost and policy
A set of surfaces whose silhouettes are one shape.
GlassSurfaceGeometry Cost and policy
Something in the render tree that can say where it is.
GlassSurfaceRecord Cost and policy
One glass surface, read at the moment it was asked.
GlassSwitch Panels and controls
A switch whose knob becomes a clear glass drop while it is held.
GlassTabBar Panels and controls
A bottom bar of tabs whose selection becomes a glass drop under a finger.
GlassTabBarMinimizer Panels and controls
Says whether the content below has scrolled down, for the GlassTabBars below it that collapse on a scroll (GlassTabBarMinimizeBehavior.onScrollDown).
GlassTabItem Panels and controls
One item of a GlassTabBar.
GlassTabItemLook Panels and controls
What a GlassTabBar resolved for one of its items, as it draws it.
GlassTextField Panels and controls
A single line of text in a glass capsule.
GlassTheme Foundations
Carries GlassThemeData down the tree.
GlassThemeData Foundations
The tokens a screen's glass reads.
GlassThermalPolicy Cost and policy
What the retake may spend on staleness under thermal pressure — the thermal lever, and a policy rather than a panic.
GlassTierChoice Cost and policy
One rung and the reason it holds.
GlassTierPolicy Cost and policy
Turns whatever an application knows into one rung.
GlassToolbarItem Panels and controls
One action of a GlassButtonGroup.
GlassTravel Composition
Declares that the glass below may move anywhere inside this widget's box, and asks the host to capture the whole box for it.
GlassTravelRegion Composition
The region the surfaces below may move within, as something they can ask.
GlassTravelScope Composition
Carries the region down to the surfaces inside it. Never notifies: the region's identity is fixed and its geometry is read when asked.
GlassUnion Composition
Draws every GlassSurface below it as one piece of glass, however far apart they are.
GradientProxyPainter Capture control
A stub of one gradient. Keeps a local mean where a flat colour would not — which is the axis a blur cannot restore: a low-pass removes what is above its cutoff and cannot bring back a mean that is no longer there.
ProxyResolution Cost and policy
The proxy's recording resolution, as an integer divisor of the device pixel ratio.
ProxyResolutionChoice Cost and policy
What the chooser decided, and enough to argue with it.
ProxyResolutionPolicy Cost and policy
Chooses the divisor.
RenderGlassAbove Composition
The render object behind GlassAbove: a marker the host reads off the tree, and nothing else — it paints, lays out and hit-tests as its child.
RenderGlassGroup Composition
The render object behind GlassGroup and GlassUnion.
RenderGlassProxy Capture control
The marker the proxy pass reads. In the real frame it is a plain proxy box.
RenderGlassSurface Foundations
The render object behind GlassSurface.
RenderGlassTravel Composition
The box behind GlassTravel. Transparent to layout, paint and hit testing.
ShadowFilter Capture control
What a draw has to look like to be dropped.
SliderGeometry Panels and controls
Where the slider's fill ends for a value, on a slider width wide.
SolidProxyPainter Capture control
A stub of one flat colour — the cheapest thing that stands for a subtree.

Enums

GlassContentDeclaration Cost and policy
Whether the host may hold a proxy that nothing it watches has changed.
GlassHardware Cost and policy
The device family whose measurements apply.
GlassLoadVerdict Cost and policy
Where a screen's glass sits against the runs that exist.
GlassProxyRole Capture control
The four declarations, in the order of how much they subtract.
GlassScrollEdgeAppearance Panels and controls
Which way a soft edge tints: toward white over light content, toward black over dark. Apple picks it from the content; see GlassScrollEdge.appearance.
GlassScrollEdgeSide Panels and controls
Which side of the scroll view the effect is on.
GlassScrollEdgeStyle Panels and controls
Apple's two styles of scroll edge effect.
GlassSheetDetent Modals
The heights a sheet from showGlassSheet rests at — UIKit's UISheetPresentationController.Detent, two of them.
GlassSurfaceCostModel Cost and policy
Which platform's measurements to read the register against.
GlassTabBarMinimizeBehavior Panels and controls
When a GlassTabBar collapses to its selected tab — iOS 26's TabBarMinimizeBehavior, two of its cases.
GlassThermalState Cost and policy
Thermal pressure, in Apple's four names — the coarser vocabulary of the two, so every Android status maps onto one of them and none of Apple's is invented.
GlassTier Cost and policy
What a surface paints. The rungs of the finish ladder, in order of what they draw rather than of what they cost.
GlassTierReason Cost and policy
Why the rung in force is the one in force.
ProxyBlurPass Cost and policy
How the residual blur reaches the atlas.
ProxyCostModel Cost and policy
How the hardware charges for a capture — which decides whether resolution is a lever at all.
ProxyDivisorReason Cost and policy
Why the chooser stopped where it did.
RetakeReason Cost and policy
Why the oracle decided what it decided.

Constants

kAppleDimmingOpacity → const double Foundations
The dimming layer Apple's guidelines put behind clear Liquid Glass over bright content: "consider adding a dark dimming layer of 35% opacity" (HIG, Materials).
kCalibratedRim → const Color Foundations
What the outline adds, and it adds rather than mixes.
kGlassAlertRadius → const double Modals
The alert's corner radius, logical px (iOS 26.5's layer.cornerRadius, a continuous corner).
kGlassAlertWidth → const double Modals
The alert's width, logical px, as iOS 26.5 draws it.
kGlassBadgeDot → const double Panels and controls
A dot badge's diameter, logical px. Layout, not a reading.
kGlassBadgeHeight → const double Panels and controls
A badge's height with a count in it, logical px — and its smallest width, so one digit is a circle. Layout, not a reading.
kGlassBadgeRed → const Color Panels and controls
iOS's systemRed in the light appearance, (255, 59, 48): the badge's fill on light glass and a light page. On dark glass, or a page whose label is light, the badge is the dark appearance's, (255, 69, 58).
kGlassCapsule → const BorderRadius Foundations
A radius larger than any box, which is how a capsule is declared.
kGlassDisabledDarkLabel → const Color Panels and controls
The label of a disabled GlassButton whose enabled label is black, and whose enabled label is white.
kGlassDisabledLightLabel → const Color Panels and controls
The label of a disabled GlassButton whose enabled label is white: tertiaryLabel in dark, (235, 235, 245) at 0.3.
kGlassDisabledOpacity → const double Panels and controls
How opaque a disabled switch or slider is, drawn as one group.
kGlassDropDuration → const Duration Panels and controls
How long the drop of a GlassSwitch or a GlassSlider takes to lift or settle.
kGlassDropOptics → const GlassOptics Panels and controls
The optics of a held drop, which are not the material's.
kGlassDropScale → const double Panels and controls
How much larger a held drop is than the resting knob, by default.
kGlassFieldHeight → const double Panels and controls
The field's height at the default text size, and its minimum (iOS 26.5's standalone search field, 44 pt): a larger text size grows it with its line, keeping 11 above and below.
kGlassFocusRingColor → const Color Panels and controls
The focus ring's colour: iOS's system blue in dark, which is also the slider's default fill.
kGlassFocusRingGap → const double Panels and controls
The gap between a control's edge and its focus ring, logical px.
kGlassFocusRingWidth → const double Panels and controls
The focus ring's stroke, logical px.
kGlassMenuRadius → const double Modals
A menu's corner radius, logical px (iOS 26.5; the engine's RSuperellipse of 31.5, fitted at 0.23 pt rms). The default of GlassPopoverAnchor.radius.
kGlassMenuRowHeight → const double Modals
The height of one GlassMenuItem of one line at the default text size, logical px (iOS 26.5: rows of 42, with 10 above the first and below the last). A row of more lines, or of larger text, is taller.
kGlassMenuWidth → const double Modals
A menu's width, logical px (iOS 26.5's UIMenu from a button, 250 wide). The default of GlassMenuAnchor.width.
kGlassMinTapTarget → const Size Panels and controls
The smallest a control may be, logical px — Apple's Human Interface Guidelines, 44 x 44 pt.
kGlassModalDim → const Color Modals
The dim behind an alert and a sheet: black at 0.20, read off iOS 26.5 over a grid of two known levels.
kGlassModalLift → const int Composition
The lift of a modal layer — a menu, a dialog, a sheet: above the page's glass and above bars lifted over it.
kGlassMorphSpacing → const double Composition
The spacing a morph's union is folded at, in logical pixels — the default of GlassMorph.spacing.
kGlassPageControlHeight → const double Panels and controls
The capsule's height, logical px. Layout, not a reading; the control is laid out kGlassMinTapTarget tall around it.
kGlassPageDot → const double Panels and controls
A page dot's diameter, logical px. Layout, not a reading.
kGlassPageDotGap → const double Panels and controls
The space between two dots, logical px. Layout, not a reading.
kGlassScaffoldActionGap → const double Panels and controls
How far the floating action stands from the screen's end edge and from the bottom bar, logical px. Layout taste, as Material's.
kGlassScaffoldBarHeight → const double Panels and controls
GlassScaffold.topBarHeight's default, logical px. Layout taste, not a measurement: Material's toolbar height, which the example's shell uses.
kGlassScaffoldBarMargin → const EdgeInsets Panels and controls
GlassScaffold.barMargin's default: the space around each bar, inside the safe area. Layout taste.
kGlassScrollEdgeDarkTint → const Color Panels and controls
The soft edge's tint at the edge over dark content: black at 0.25, read over content whose mean was a mid grey.
kGlassScrollEdgeHardFill → const Color Panels and controls
The hard edge's band in the light appearance: a near-opaque white, 0.90 over both a dark and a light field.
kGlassScrollEdgeHardFillDark → const Color Panels and controls
The hard edge's band in the dark appearance: the dark background, black, at 0.90 (51 → 5 and 230 → 23 over the two fields).
kGlassScrollEdgeHardSigma → const double Panels and controls
The hard edge's blur: a bound, not a reading — see the file comment.
kGlassScrollEdgeLightTint → const Color Panels and controls
The soft edge's tint at the edge over light content: white at 0.85.
kGlassScrollEdgeSigma → const double Panels and controls
The soft edge's blur, logical px (read as 1.55–1.67).
kGlassSegmentDropGrow → const Size Panels and controls
How far past the resting capsule the held drop reaches, across and down, logical px (iOS 26.5: 86 x 28 -> 110 x 44).
kGlassSegmentDropWiden → const double Panels and controls
How much of the backdrop past its box the held drop shows (iOS 26.5: a margin of 2.9 pt is the better of two poor fits).
kGlassSegmentTrack → const Color Panels and controls
The track's fill: iOS's tertiarySystemFill, read off the simulator as (116–127) at 0.12.
kGlassSheetInset → const double Modals
How far the sheet stands in from the window's sides and bottom, and below the top safe area, logical px (iOS 26.5, the medium detent).
kGlassSheetRadius → const double Modals
The sheet's corner radius, logical px (iOS 26.5; the engine's RSuperellipse of 36, fitted at 0.54 device px rms).
kGlassStepperRepeatDelay → const Duration Panels and controls
How long a held half waits before it starts to repeat, and how often it repeats after that.
kGlassStepperRepeatInterval → const Duration Panels and controls
See kGlassStepperRepeatDelay.
kGlassStepperSize → const Size Panels and controls
The stepper's capsule, logical px: UIStepper's 94 across, and the segmented control's 32-px track down.
kGlassSwitchDropWiden → const double Panels and controls
How far past its own box the held switch's drop shows, logical px — the iOS switch's drop minifies what is under it (×0.85 across, ×0.79 down on a 58 × 38 pt drop), which is this one margin rather than one zoom. The slider's drop, read the same way, does not minify, and its default is 0. See GlassOptics.widen.
kGlassSwitchSize → const Size Panels and controls
The iOS 26 switch's track, logical px. Its resting knob is 38 x 24.
kGlassTabAccessoryHeight → const double Panels and controls
The height of GlassTabBar.bottomAccessory's glass, logical px. Layout taste: the bar's minimum tap target and a little.
kGlassTabDropGrow → const double Panels and controls
How much larger than the resting capsule the held drop is, on every side, logical px.
kGlassTabDropZoom → const double Panels and controls
How much the held drop magnifies the bar under it.
kGlassTabMinimizeScroll → const double Panels and controls
How far the content has to scroll one way, logical px, before a GlassTabBarMinimizer says so: past this down, the bars collapse; past it up, they expand. Layout taste — enough to ignore a finger settling, short enough that a deliberate scroll is answered at once.
kGlassToolbarHeight → const double Panels and controls
The group's height, and the circle a group of one is, as iOS 26.5 draws it.
kGlassToolbarItemWidth → const double Panels and controls
Each item's width in a group of more than one: 159 pt for three on iOS 26.5.
kHighContrastRimWidthLogical → const double Foundations
Width of the outline under the platform's increase-contrast switch, logical px.
kMaterialScaleDeltaE → const double Foundations
ΔE between Apple's Glass.regular and Glass.clear on one backdrop, read on an iPad: the external unit the package's damage numbers are scaled by.
kMaxFusedShapes → const int Composition
Shapes one fused draw can carry.
kMaxRippleWaves → const int Foundations
The most waves one draw evaluates; kMaxWaves in the shader.
kNonTextContrast → const double Foundations
WCAG 2.2's contrast floor for a component's boundary against what is next to it (SC 1.4.11, non-text contrast).
kRimWidthLogical → const double Foundations
Width of the outline, in logical pixels — measured, not chosen.
kTextContrastAA → const double Foundations
WCAG 2.2's AA floor for body text (SC 1.4.3).

Properties

debugPaintGlassSurfaces ↔ bool Foundations
Outlines every registered surface and prints nothing.
getter/setter pair

Functions

showGlassDialog<T>({required BuildContext context, required WidgetBuilder builder, bool barrierDismissible = false, String barrierLabel = 'Dismiss', Duration transitionDuration = const Duration(milliseconds: 250)}) → Future<T?> Modals
Shows builder's widget — a GlassAlert, typically — over a dim, centred, in the navigator's overlay.
showGlassSheet<T>({required BuildContext context, required WidgetBuilder builder, GlassFinish? finish, bool showGrabber = true, bool barrierDismissible = true, String barrierLabel = 'Dismiss', BoxConstraints? constraints, List<GlassSheetDetent> detents = const <GlassSheetDetent>[GlassSheetDetent.medium], GlassSheetDetent? initialDetent, ValueChanged<GlassSheetDetent>? onDetentChanged, GlassFinish? largeFinish}) → Future<T?> Modals
Shows builder's widget in a glass sheet rising from the bottom, over a dim. Dragged, it follows the finger; dragged down, it goes past a third of its height or on a flick.
unionBlendRadius(List<Rect> boxes, List<double> radii) → double Composition
The smallest blend radius that folds boxes into one connected silhouette, in logical pixels — what a GlassUnion hands the shader instead of a declared spacing.

Typedefs

GlassTabItemBuilder = Widget Function(BuildContext context, GlassTabItemLook look) Panels and controls
Builds an item's icon or label from what the bar resolved for it.
ProxyDamage = ({double deltaE, bool measured}) Cost and policy
A damage figure, and whether it is a reading or a bound.
ProxyRouteCost = ({double factor, bool measured}) Cost and policy
What the whole route costs at a divisor, relative to the same route at full resolution — and whether that point was measured or interpolated between two that were.