Safari 26 "Liquid Glass" — facts, gotchas, and what to do

1. The model

iOS 26 and iPadOS 26 gave Safari a "Liquid Glass" chrome: the status bar (top) and the address/tab bar (bottom) are translucent overlays that show whatever the page paints behind them, live, as you scroll. Apple dropped `theme-color` as the bar tint — the bars just reflect the page now.

This is the iPhone Safari layout model. It also applies on iPadOS — and there it's gated by the browser window width, not the device: a narrow Safari window (Split View, Slide Over, a portrait small iPad, or just a narrow window) gets the iPhone model with the glass bars; a wide one gets the desktop-ish model. So decide "is this the glass model?" by width, not by user-agent (e.g. innerWidth <= 760), because the same iPad flips between the two.

Think of the screen as two viewports:

• Layout / large viewport — the full physical screen, including behind both

bars. 100vh, 100lvh, and window.innerHeight all measure this large viewport. `innerHeight` is constant — it does NOT change when the bars show/hide or the keyboard opens.

• Visual / small viewport — only the area between the bars.

window.visualViewport.height and 100svh measure this; `100dvh` tracks it dynamically (it shrinks when the keyboard opens).

So on this model `innerHeight` = the large viewport (constant), while visualViewport.height = the small viewport (changes). Any "fill the visible area" math must be driven off visualViewport, never off innerHeight/vh.

The bars sit over the edges of the layout viewport and composite whatever DOM pixels are painted there.

The bar tint — Safari derives it from your CSS (theme-color is dead)

Beyond the live bleed, Safari 26 tints the glass with a solid colour derived from your CSS. theme-color is ignored (it still parses; the value does nothing). The derivation, in order:

1. the background-color of a `fixed`/`sticky` element at that edge — it borders

the "obscured content inset" (where the bar overlaps content), so Safari extends its colour into the bar for continuity;

1. else the `body` background-color — html's is ignored, and this same

body colour is what the overscroll "rubber-band" shows, so match `body` to your design or you get flashes (a white body on a dark site flashes white on overscroll);

1. else the system default.

• Derived from the CSS, not live from JS — mutating a background via JS after paint

does not re-tint the bar (Safari re-derives on scroll/layout, not on a bare style change).

• Solid vs translucent flips control: a solid colour tints the bar to exactly that

colour (yours); an `rgba()`/semi-transparent background makes Safari sample the computed colour showing through → unpredictable. Use opaque for control.

• Users can disable tinting (iOS: Settings ▸ Apps ▸ Safari ▸ Tabs ▸ "Allow Website

Tinting") → the bar reverts to system default, so your design must still read then.

• The blur is softer on iPhone than macOS — more of the page shows through the bar,

so a colour mismatch between your sampled edge element and the content behind it is more visible/jarring here. Getting the sampled colour right matters most on iPhone.

The tint is a feature — decide your intent:

• **Want the bar tinted to match a header/brand (i.e. you do NOT want a transparent

status bar): give a top element a solid `background-color` and let Safari sample it. sticky is the reliable trigger** — a bare fixed header's colour is sampled inconsistently (see §2 and WebKit #301756); setting body's background also works.

  header { position: sticky; top: 0; background: #1a1a1a; } /* → status bar #1a1a1a */

• Want an immersive / transparent bar: control this on the **edge (fixed/sticky)

element*, not by stripping `body`. Keep an opaque `background` off the edge element and use §2's field-note knobs (a `fixed; top:0` header keeps the top bar glassy). Leave `body` painted — §5/§2 need it for the overscroll rubber-band and the load-flash guard, so don't remove it here; a painted `body` is only the fallback* tint, and the finicky edge-element behaviour (§2, WebKit #301756) is what actually decides whether the bar goes transparent.

Same-mechanism gotchas: a fixed full-screen modal backdrop (inset: 0; background: rgba(0,0,0,.5)) can get sampled and darken the whole bar — but fixed-element sampling is unreliable (see the §2 "fixed backdrop is a trap" note for the flip side, where the fixed layer is ignored instead); two fixed elements (header + footer) → Safari picks one, not reliably; and there is *no `theme-color` override — the CSS is the API* (WebKit #301756 tracks fixed-element tinting issues).

2. Facts we established (iOS/iPadOS 26, verified on-device)

• A black/grey bar is just your page background showing through. If html/

body background is dark, the bars are dark. Paint it your page colour and the bars take that colour. This is also the flash you see on first load.

• *Only scrolled document content bleeds under the bars.* A genuinely tall,

scrollable document paints behind the bars. A page sized to exactly the viewport does not bleed — it stops at the bar edge; the background shows behind the bars.

• `innerHeight` is constant; `visualViewport.height` is what changes (bars,

keyboard). Measure layout with innerHeight; detect keyboard/bar state with visualViewport.

• **A flex:1 / overflow:auto child inside a dvh/vh-sized box often won't

scroll (it grows to its content and the gesture falls through to the page). Try the standard fix first: the usual culprit is `min-height:auto` on a flex item — set min-height:0* (or `min-height:0` on the flex child + the scroll area) and it typically scrolls. Where that isn't enough, we've observed iOS 26 behaving as if `dvh`/`vh` heights resolve as indefinite for the child (so it never gets a scrollable box); the reliable escape is a definite px* height (derived from innerHeight) on the scroll container. Verify per case.

• The glass bars cache their backdrop. They only re-sample on a **scroll or

layout change — changing a background colour or repainting a canvas alone leaves the bar stale**. A 1px scroll nudge forces a re-composite.

• Centre-scroll math must be measured, not `vh`-based — vh/innerHeight

(large) ≠ visualViewport (small), so a vh calculation leaves a strip. Measure the visible band with visualViewport.height.

position:fixed is the big one

A position:fixed element is clipped to the visual viewport, so:

• The element never paints behind a bar, and its shadow is cropped at the bar

edge. (A fixed button anchored with env(safe-area-inset-bottom) still has its drop-shadow chopped where the bar starts.)

• *Worse: a full-screen / overlay fixed element can collapse the whole page's*

bleed — once it's on screen, the rest of the page starts clipping at the bar edge too, and the clip can persist after the fixed element is gone** (until a scroll/layout change). We reproduced this just by opening & closing a position:fixed bottom-sheet + backdrop.

So the damage is sometimes just the element (cropped shadow), sometimes the entire page (collapsed bleed) — depending on the element and where it sits. Treat any position:fixed as a bleed-breaker on this model and verify. (A "fixed full-screen backdrop" is an unreliable tint source: in our build the in-flow background behind it did the tinting and the fixed layer added nothing — the flip side of the same finicky fixed-element sampling that elsewhere lets a fixed rgba backdrop darken the bar (§1). Either way it crops its children, so don't use a fixed layer to control the bar tint — use a sticky element or body.)

*Field note — a top-pinned header and the top-bar tint is a separate axis. The bleed/shadow rule above is about content clipping; whether the top status bar stays transparent under a header pinned to the very top behaves differently — and here `fixed` is actually the safe* choice:

Offsets below are written as Tailwind classes (what was tested): top-0 = top: 0, top-1 = top: 0.25rem, top-2 = top: 0.5rem. (Nonzero CSS lengths need a unit — top: 1/top: 2 are invalid; use 0.25rem/0.5rem.)

• position: fixed at top-0 — top status bar stays transparent. fixed does

not kill it here.

• position: sticky at top-0 — kills it (bar goes opaque). top-1 still kills

it; `top-2` restores the transparent bar — a sticky top header needs a small offset off the bar edge to keep it.

So "never position:fixed" is a bleed/shadow rule, not a top-tint one: for a top header specifically, position: fixed at the top — or a sticky header with a ≥ top-2 (0.5rem) offset — keeps the bar transparent. Single-setup observation on iOS 26.x; re-verify on your build.

Why (ties to §1's tint derivation): a sticky header with a solid `background-color` sitting at the very edge is exactly what Safari samples into the bar — so it tints, it doesn't "break"; the top-2 offset stops it bordering the bar edge, so it isn't sampled. In this test a fixed; top:0 header left the bar transparent even so — fixed-element sampling is less reliable (WebKit #301756). Practical rule: for a deliberate tint, sticky + a solid bg is the reliable trigger; for transparent, fixed; top:0 or sticky with a ≥ top-2 offset.

The keyboard bug (WebKit #297779)

• Focusing an input opens the soft keyboard; iOS scrolls the window to keep

the input visible.

• innerHeight stays constant; visualViewport.height shrinks. iOS fires **one

visualViewport resize per transition* (one on open, one on close — not* one per animation frame).

• After dismissal the viewport can stay shifted — visualViewport.offsetTop

doesn't reset to 0 and the height can stay ~24px short — so content looks "slid up by the keyboard height." Affects fixed/sticky elements and any scroll-positioned layout. (Even apple.com is affected.)

• Status (as of iOS 26.x): WebKit #297779 is acknowledged by Apple; iOS 26.1

reduced the residual offset but reports of the stuck ~24px offsetTop persisted into later 26.x releases. Treat the workaround below as still needed and re-verify on your current OS build before assuming it's fixed.

• Because `innerHeight` is constant, your intended scroll position is the

same whether the keyboard is open or closed — so you can restore it the moment the field blurs, without waiting for the (late) close event.

3. For a normal website, all of this Just Works

A plain, tall, scrolling page — normal background, content in flow, ordinary fixed header/footer, native inputs — bleeds correctly, tints the bars, and recovers from the keyboard on its own. You usually need to do nothing. A 1990s long-article page renders perfectly. If you see black bars or clipping on a simple page, you've added something from §4.

4. But if you get creative, BEWARE

Immersive/edge-to-edge layouts, fixed full-screen canvases, custom drawers/ modals/sheets, gesture-driven panning, themeable/live backgrounds, canvas effects — these break the "just works" assumptions. Problems we hit:

• Black bars — from a dark app-shell/body background.
• Content clipped at the bar edge — from a viewport-height, non-scrolling

shell (height:100vh + overflow:hidden, a 100dvh flex app, or position:fixed; inset:0). It can't bleed.

• Cropped shadows / collapsed bleed — from position:fixed chrome, drawers,

or backdrops (see §2).

• An inner scroll area that won't scroll — because its container is sized in

dvh/vh (indefinite); the gesture scrolls the page instead.

• The page scrolling away — a drawer's inner scroll chains to the document

and drifts an immersive/centred layout.

• The bars lagging a live colour/content change — the cached backdrop.
• The layout shifting and not recovering after the keyboard — §2 keyboard bug.
• A canvas blur not rendering — see §6.

5. Suggestions (case-dependent — pick what the situation needs)

First, always: paint html/body your page colour in CSS (not JS — JS is too late and you get a first-paint flash). If the colour is dynamic, bake a sane default into CSS and update it live afterwards.

If you only need the bars to match a colour (content needn't go under them): the CSS background above is often enough. Make sure no opaque dark element covers the bar region.

If you need content to bleed under the bars (immersive/edge-to-edge):

• Build a scroll band taller than the screen (e.g. innerHeight + 2·PAD px,

PAD≈200) painted the page colour, and centre it by measurement (not vh) on mount + resize + orientationchange. It then overflows ≈PAD under each bar and fills both at once (a screen-height band can't — pushing it up to cover the top uncovers the bottom).

• Size the band in definite px (from innerHeight), not `dvh` — dvh

shrinks with the keyboard and would resize the whole thing.

• Put all chrome inside the band, in a frame inset by `PAD` (= the visible

region), with normal insets + env(safe-area-inset-*). Never `position: fixed` — that re-breaks the bleed and re-crops shadows.

• Stop gestures from scrolling the band: touch-action:none on the interactive

surface (canvas does its own pan/zoom) + overscroll-behavior:none.

Drawers / bottom-sheets / modals (the part people get wrong):

• Make the sheet and its backdrop **position:absolute inside the band, NOT

fixed (fixed collapses the bleed). Anchor the sheet under the bottom glass and add equal bottom padding** inside its scroll area so content clears the bar.

• Give the sheet a definite px height so its inner body actually scrolls;

pin the header with position:absolute (outside the scroll body) so only the body rubber-bands.

• Lock the page while the sheet is open with overscroll-behavior:contain on

the sheet's scroll body + touch-action:none on the backdrop — not position:fixed/overflow:hidden on body (both break the bleed or jump the scroll).

Live/themeable background colour: update the document background live, then do a 1px scroll nudge (debounced) to force the bars to re-composite — otherwise they lag until the next scroll/layout.

Soft keyboard: capture the scroll position on focusin (page is settled then); on focusout restore it — you can do this immediately because innerHeight is constant, so the target is already correct. Back it up by also restoring when the visualViewport resize reports the height back near full, and finish with a 1px scroll jiggle to reset the stuck offsetTop. Don't pin the scroll while the keyboard animates (iOS re-scrolls and undoes it).

6. Related WebKit canvas gotcha (not glass, but found here)

CanvasRenderingContext2D.filter (e.g. ctx.filter='blur(4px)') silently doesn't render by default on iOS/iPadOS Safari — the effect is a no-op even though it works in Chrome. WebKit #198416 is RESOLVED FIXED (implemented in 2024), but as of Safari/iOS 18–26.x the feature ships disabled by default, behind a flag — so in practice you can't rely on it. Use `shadowBlur` instead (draw the shape far off-canvas and keep only its blurred shadow, tinted as needed). SVG feGaussianBlur is fine; it's only the canvas 2D filter property that's off by default.

Provenance

Established iteratively, on-device, building the Made in Lantau "Lantau Type Map" (a full-screen canvas studio) for iOS Safari 26. Every fact in §2 and every problem in §4 was reproduced and fixed on a real iPhone/iPad.

§1's model claims are corroborated beyond that build: the theme-color drop and "bars reflect the page / sample a fixed-or-sticky edge element's background-color then fall back to body" behavior match independent Safari 26 reporting (Apple published no official web-dev docs for it; the specific derivation order below is the one write-up cited in References). §1's bar-tint derivation order (fixed/sticky edge → body → default; html ignored; sampled at render; overscroll rubber-band = body) follows Ben Nasedkin's write-up; the less-reliable fixed-element case is WebKit #301756. The `innerWidth <= 760` gate is a rule of thumb, not an Apple constant — the split is by window width, but the exact breakpoint isn't documented; measure/treat it as approximate and tune per layout rather than copying 760 verbatim.

The §2 top-bar-tint thresholds (fixed; top:0 keeps the top bar transparent; a sticky top header needs a ≥ top-2 offset) are a single-setup on-device observation — confirmed once, not yet corroborated by outside write-ups. Treat the exact top threshold as approximate and re-verify.

Everything here is as-of iOS/iPadOS 26.x; behavior is evolving across point releases (see the keyboard-bug status note in §2). Re-verify on your target OS build before relying on any specific fact.

References: WebKit #297779 (keyboard/visualViewport offset; acknowledged, partly improved in 26.1), WebKit #198416 (canvas ctx.filter; RESOLVED FIXED but disabled by default in shipping Safari 18–26.x), WebKit #301756 (fixed-element toolbar tinting), and Ben Nasedkin, "Why iOS 26 Safari Toolbar Colors Work Differently" (nasedk.in) — the source for §1's tint-derivation order.