The lens and its style

A liquid-glass lens you can place anywhere in the widget tree.

Unlike the children: slot of LiquidGlassView, this lens is layout-driven: it has no position or size parameters — it is exactly where layout puts it and exactly as big as its constraints/child make it (wrap it in a SizedBox to give it explicit dimensions).

Render modes (resolved automatically)

• Impeller (ImageFilter.isShaderFilterSupported): the lens refracts the live backdrop — whatever your app painted behind it. No LiquidGlassView and no background widget needed at all; drop it over any UI and it works.
• Skia / Web with an ancestor LiquidGlassView that has a backgroundWidget: the lens refracts the view's captured background, wherever the lens sits inside the view's child.
• Skia / Web without a view (or without a background): refraction is impossible, so the lens degrades to a frosted look — backdrop blur + tint + border, no refraction — and logs a one-time debug warning.

The mode is an implementation detail: the widget tree you write is identical in all three cases.

Lenses inside scrollables (Impeller)

Android's stretch overscroll effect isolates the scrollable's content into its own compositing layer while the stretch plays. A BackdropFilter-based lens inside that layer can no longer see the real backdrop and renders black at both scroll edges. Disable the overscroll indicator for scrollables that contain lenses:

Glass without the shader: a frosted surface with the lens' own rim light, drawn from plain canvas geometry.

A LiquidGlassLens gets its look from the glass shader: every pixel measures its own distance to the shape's SDF, reads the background under it, bends it, and lights itself. That is what makes the rim feel like an optical consequence of the glass — and it is also why it costs a FragmentProgram, a program warm-up, and (on Impeller) a slot in the lens budget.

This is the light version of that. It gives up refraction, which is the half that needs a shader, and keeps the half that does not: the frost, the tint, and the rim.

The rim is a lens' specular, evaluated on the Dart side: the outline is sampled into a ring of points, each point's outward normal is run through the shader's own formulas — the same ramp across the edge, the same pair of arcs on the light's axis — and the result is a few drawVertices calls per light. blur is the glass itself; the rim is its edge. No shader asset, no FragmentProgram, nothing to warm up.

It takes the ordinary LiquidGlassShape and the lens' two lights: the specular, and the glow under it, each drawing the same band here as it does on a lens. Neither light reads the backdrop, so a glow costs nothing but its own mesh. The silhouette comes from the same outline a lens clips to, so all three corner styles — circular, squircle, and the continuous capsule corner — are reproduced exactly.

A painted rim

The rim is painted last, over the frost, the color and the child, and reads nothing back. Each light is blended into the finished surface with overlay, so it brightens whatever it lies over and keeps that colour: red where the surface is red, blue where it is blue. A plain white floor is screened over the blend so the rim still shows over black, where overlay has nothing to lift. A light's own color is multiplied in after that, so a grey light is a grey rim.

Because it reads nothing, the rim holds up wherever a backdrop read does not: through page transitions, under the overscroll stretch, inside any layer that moves.

There is no refraction — no edge bend. magnification is the flat-slab half only; the rim itself does not shift with the content behind it the way glass does.

It is an inner border

The rim is clipped to the outline, like a lens clips its shader, so it is drawn strictly INSIDE the box — brightest against the edge and falling away inward, never hanging past it. Give the widget the size of the surface the border belongs to, not a box around it.

When to reach for it

For a surface that is not a lens — a card, a list row, a sheet, a focus ring — and for the many-of-them cases where real lenses would be too expensive: long lists, low-end devices, the web.

The frost is its only backdrop read. blur: 0 at a magnification of 1 drops that read too, and the surface reads nothing at all.

The look of a liquid-glass surface, bundled into one reusable descriptor: its shape, the two lights of its border (specular and glow), its fill (color, blur, saturation, shadow) and how it bends the content behind it (refractionIndex, refractionWidth, magnification, dispersion).

This is the single styling vocabulary shared across the library — LiquidGlassLens and the components (buttons, bars, the nav pill, …) all describe their glass with the same object. Change one facet with copyWith:

Non-refracting consumers — e.g. the static (non-glass) selection pill or the frosted fallback — read the subset they can render and simply ignore the refraction fields.

The outline of a liquid-glass surface: its corner curve and radius.

One concrete class: the corner curve is chosen by cornerStyle (or one of the LiquidGlassShape.roundedRectangle / LiquidGlassShape.squircle / LiquidGlassShape.continuousRoundedRectangle convenience constructors). The border lives on the style: see LiquidGlassStyle.specular and LiquidGlassStyle.glow.

One light on a glass border: a band along the outline, lit as a pair of opposing arcs.

A LiquidGlassStyle carries two of them: specular, the bright highlight, and glow, the softer band that fills the sides the specular leaves dark.

The contact shadow of a glass pill: a soft dark band that hugs the rim and pools underneath, so the glass reads as sitting in the surface rather than floating flat on it.

Wrap the lens, don't go inside it

This is a parent of the glass, not its content:

That placement is the whole point. A lens clips its own child to its outline, so a shadow passed as content can only ever darken the inside — the half that pools below the pill would be cut away, which is the half that actually reads as contact. As a parent it is unclipped, and free to spill past the edge.

It paints behind what it wraps (CustomPaint.painter, before the child), so the glass sits over its own shadow. That is also what keeps a rest state honest: a solid pill drawn over the glass covers the shadow with it, instead of wearing a dark band it should never have.

It never touches what it wraps, so it composes with any lens.

The shape

The shadow is cast by a ring, not by the pill itself: an outer capsule pushed out by 1 px horizontally and blur/2 vertically, minus an inner capsule pulled in by blur/2 vertically. Only a band straddling the rim casts anything, so the middle of the glass stays clear.

That ring is then displaced downward by offset (blur + 2 by default) and blurred. The upper arc lands just inside the top rim; the lower arc lands entirely below the pill. One ring gives both the inner rim contact and the drop beneath.

It composites with BlendMode.multiply, so it darkens whatever is under it — the glass on the inside, the page on the outside — instead of laying flat grey over both.

Keeping it out of the glass

insideGlass decides whether the part of the ring that falls under the outline is drawn at all. true (the default) is the contact look above: the upper arc darkens the inside of the rim. false clips the ring to the outside of the outline and paints it over the glass instead of behind it — visually the same drop beneath, but a lens's backdrop sample never contains it, so a refracting rim cannot pull it into the interior as a dark inner band.

Under a deformed lens

A squashed or stretched lens keeps its authored corner radius and stretches the whole outline (the shader's u_shapeScale), so its caps go elliptical rather than re-rounding. Pass the same scale the lens is drawn with and the ring follows that ellipse; leave it at (1, 1) and the ring is a plain capsule.

The corner curve of a LiquidGlassShape.

Selects which corner SDF the shader draws and which exact clip path the renderers use. The single axis of variation between the old RoundedRectangleShape / SquircleShape / ContinuousRoundedRectangleShape classes, now an explicit value.

How a lens is clipped to its outline. Every LiquidGlassShape carries its own LiquidGlassShape.clipQuality.