Swiftui Liquid Glass

SwiftUI Liquid Glass

Liquid Glass is the dynamic translucent material introduced in iOS 26 (and iPadOS 26, macOS 26, tvOS 26, watchOS 26). It blurs content behind it, reflects surrounding color and light, and reacts to touch and pointer interactions. Standard SwiftUI components (tab bars, toolbars, navigation bars, sheets) adopt Liquid Glass automatically when built with the iOS 26 SDK. Treat custom Liquid Glass as a controls/navigation-layer effect, not a general content background. Use the APIs below for custom views and controls that need that functional layer.

See references/liquid-glass.md for the full API reference with additional examples.

Contents

• Workflow
• Core API Summary
• Code Examples
• Common Mistakes
• Review Checklist
• References

Workflow

Choose the path that matches the request:

1. Implement a new feature with Liquid Glass

1. Identify target surfaces (floating controls, custom bars, transient controls). 2. Decide shape, prominence, and whether each element is a real control or static status. 3. Wrap grouped glass elements in a GlassEffectContainer. 4. Apply .glassEffect() after layout and appearance modifiers. 5. Add .interactive() only to tappable/focusable elements. 6. Add morphing transitions with glassEffectID(_:in:) where the view hierarchy changes with animation. Put glassEffectTransition(_:) on the inserted or removed glass child, not on the always-present container. Name the transition choice: .matchedGeometry for nearby effects inside container spacing; .materialize for distant insertion/removal or no geometry match. 7. Gate with if #available(iOS 26, *) and provide a fallback for earlier versions.

2. Improve an existing feature with Liquid Glass

1. Find custom control or navigation backgrounds that can be replaced with .glassEffect(). 2. Wrap sibling glass elements in GlassEffectContainer for blending and performance. 3. Replace custom glass-like buttons with .buttonStyle(.glass), .buttonStyle(.glassProminent), or configurable styles such as .buttonStyle(.glass(.clear)). Use .glass(_:) when the button needs a specific tint or variant; reserve .glassProminent for high-emphasis primary actions. 4. Add morphing transitions where animated insertion/removal occurs.

3. Review existing Liquid Glass usage

Run through the Review Checklist below and verify each item.

Core API Summary

glassEffect(_:in:)

Applies Liquid Glass behind a view. Default: .regular variant in a Capsule shape.

nonisolated func glassEffect(
    _ glass: Glass = .regular,
    in shape: some Shape = DefaultGlassEffectShape()
) -> some View

Glass struct

Chain them: .regular.tint(.blue).interactive()

GlassEffectContainer

Wraps multiple glass views for shared rendering, blending, and morphing.

GlassEffectContainer(spacing: 24) {
    // child views with .glassEffect()
}

The spacing controls when nearby glass shapes begin to blend. Match or exceed the interior layout spacing so shapes merge during animated transitions but remain separate at rest.

Morphing & Transitions

Transition decision: use .matchedGeometry for nearby effects inside the container's spacing; use .materialize for distant insertion/removal or when no geometry match should occur; use .identity only when no transition animation is wanted.

Button Styles

Button("Action") { }
    .buttonStyle(.glass)           // standard glass button

Button("Primary") { }
    .buttonStyle(.glassProminent)  // prominent glass button

Button("Media") { }
    .buttonStyle(.glass(.clear))    // configurable variant; verify contrast

Scroll Edge Effects and Background Extension (iOS 26+)

These complement Liquid Glass when building custom toolbars and scroll views:

ScrollView {
    content
}
.scrollEdgeEffectStyle(.soft, for: .top)  // Configures edge effect at scroll boundaries

// Duplicate view into mirrored copies at safe area edges with blur (e.g., under sidebars)
content
    .backgroundExtensionEffect()

ToolbarSpacer (iOS 26+)

Creates a visual break between items in toolbars:

.toolbar {
    ToolbarItem { Button("Edit") { } }
    ToolbarSpacer(.fixed)
    ToolbarItem { Button("Share") { } }
}

Code Examples

Glass button with availability gate

if #available(iOS 26, *) {
    Button("Show Status") { showStatusDetails() }
        .buttonStyle(.glass)
} else {
    Button("Show Status") { showStatusDetails() }
        .buttonStyle(.bordered)
}

Grouped glass shapes in a container

let symbols = ["pencil", "eraser.fill", "lasso"]

GlassEffectContainer(spacing: 24) {
    HStack(spacing: 24) {
        ForEach(symbols, id: \.self) { symbol in
            Image(systemName: symbol)
                .frame(width: 56, height: 56)
                .glassEffect()
        }
    }
}

Nearby morphing transition

@State private var isExpanded = false
@Namespace private var ns

var body: some View {
    GlassEffectContainer(spacing: 40) {
        HStack(spacing: 40) {
            Image(systemName: "pencil")
                .frame(width: 80, height: 80)
                .glassEffect()
                .glassEffectID("pencil", in: ns)

            if isExpanded {
                Image(systemName: "eraser.fill")
                    .frame(width: 80, height: 80)
                    .glassEffect()
                    .glassEffectID("eraser", in: ns)
                    .glassEffectTransition(.matchedGeometry)
            }
        }
    }

    Button("Toggle") {
        withAnimation { isExpanded.toggle() }
    }
    .buttonStyle(.glass)
}

For distant inserted or removed glass that should not morph from a nearby control, use .glassEffectTransition(.materialize) on the conditional child instead.

Unioning views into a single glass shape

@Namespace private var ns

GlassEffectContainer(spacing: 20) {
    HStack(spacing: 20) {
        ForEach(items.indices, id: \.self) { i in
            Image(systemName: items[i])
                .frame(width: 80, height: 80)
                .glassEffect()
                .glassEffectUnion(id: i < 2 ? "group1" : "group2", namespace: ns)
        }
    }
}

Tinted glass icon control

struct GlassIconControl: View {
    let icon: String
    let tint: Color
    let action: () -> Void

    var body: some View {
        Button(action: action) {
            Image(systemName: icon)
                .font(.title2)
                .padding()
        }
        .buttonStyle(.glass(.regular.tint(tint)))
    }
}

Clear glass action over bright content

if #available(iOS 26, *) {
    ZStack {
        Capsule()
            .fill(.black.opacity(0.28))

        Button {
            playRecap()
        } label: {
            Label("Play", systemImage: "play.fill")
                .font(.headline)
                .padding(.horizontal, 8)
        }
        .buttonStyle(.glass(.clear))
    }
    .fixedSize()
} else {
    Button("Play", systemImage: "play.fill") { playRecap() }
        .buttonStyle(.borderedProminent)
}

Use clear glass only when the background still leaves labels and symbols readable. On bright or busy backgrounds, add a subtle dimming layer or choose a more opaque button style.

Static status count, not a toolbar control

VStack(spacing: 8) {
    Text("24")
        .font(.headline.monospacedDigit())
        .accessibilityLabel("24 options expiring")

    Text("Options Expiring")
        .font(.subheadline)
        .foregroundStyle(.secondary)
}
// Keep read-only status out of toolbar control slots and do not add .interactive().

Common Mistakes

DON'T: Apply Liquid Glass to every surface

Overuse distracts from content. Liquid Glass belongs in the controls/navigation layer; do not use it to decorate static content containers.

// WRONG: Glass on everything
VStack {
    Text("Title").glassEffect()
    Text("Subtitle").glassEffect()
    Divider().glassEffect()
    Text("Body").glassEffect()
}

// CORRECT: Static content stays in the content layer
VStack {
    Text("Title").font(.title)
    Text("Subtitle").font(.subheadline)
    Divider()
    Text("Body")
}

Button("Add") { addItem() }
    .buttonStyle(.glass)

DON'T: Make static status look tappable

Counts, badges, summaries, and read-only status chips should not live in toolbar action slots or use .interactive() unless they initiate an immediate action. If a badge belongs to a real toolbar action, make the action one accessible control and keep the badge subordinate to that control.

DON'T: Nest GlassEffectContainer for one related group

Use one container for the related glass group so rendering, blending, and morphing scope stay predictable.

// WRONG
GlassEffectContainer {
    GlassEffectContainer {
        content.glassEffect()
    }
}

// CORRECT: Single container wrapping all glass views
GlassEffectContainer {
    content.glassEffect()
}

DON'T: Add .interactive() to non-interactive elements

.interactive() adds visual affordance suggesting tappability. Using it on decorative or read-only status glass misleads users.

DON'T: Apply .glassEffect() before layout modifiers

Glass calculates its shape from the final frame. Applying it before padding/frame produces incorrect bounds.

// WRONG: Glass applied before padding
Text("Label").glassEffect().padding()

// CORRECT: Glass applied after layout
Text("Label").padding().glassEffect()

DON'T: Forget accessibility testing

Always test with Reduce Transparency and Reduce Motion enabled. System settings can remove or modify translucency and motion, so verify custom glass content remains readable.

DON'T: Skip availability checks

Liquid Glass requires iOS 26+. Gate with if #available(iOS 26, *) and provide a fallback.

Review Checklist

• [ ] Availability: if #available(iOS 26, *) present with fallback UI.
• [ ] Container: Multiple glass views wrapped in GlassEffectContainer.
• [ ] Modifier order: .glassEffect() applied after layout/appearance modifiers.
• [ ] Interactivity: .interactive() used only where user interaction exists.
• [ ] Status vs action: Static counts/status are not toolbar controls and do not expose press/hover affordance.
• [ ] Transitions: glassEffectID used with @Namespace for morphing animations.
• [ ] Transition type: .matchedGeometry for nearby effects; .materialize for distant ones, applied to the conditional glass child.
• [ ] Consistency: Shapes, tints, and spacing are uniform across related elements.
• [ ] Performance: Glass effects are limited in number; container used for grouping.
• [ ] Accessibility: Tested with Reduce Transparency and Reduce Motion enabled.
• [ ] Button styles: Standard .glass, .glassProminent, or configurable .glass(_:) used for buttons; .glass(_:) is primary when a tint or clear variant is required.
• [ ] Clear glass contrast: Clear glass over bright content has a dimming/contrast treatment or uses a more legible style.
• [ ] Concurrency: IDs passed to glassEffectID / glassEffectUnion are Sendable; MainActor-annotated Liquid Glass APIs stay in SwiftUI UI code.

References

• Full API guide: references/liquid-glass.md
• Apple docs: Applying Liquid Glass to custom views
• Apple docs: Adopting Liquid Glass

Liquid Glass API Reference for SwiftUI

Contents

• Overview
• glassEffect(_:in:)
• Glass
• GlassEffectContainer
• glassEffectID(_:in:)
• glassEffectUnion(id:namespace:)
• glassEffectTransition(_:)
• GlassEffectTransition
• Button Styles
• DefaultGlassEffectShape
• Scroll Edge Effect
• Background Extension (Split Views)
• Availability Gating
• Performance Guidelines
• Accessibility Considerations
• Best Practices Summary
• Apple Documentation Links

Overview

Liquid Glass is a dynamic translucent material available on iOS 26.0+, iPadOS 26.0+, macOS 26.0+, Mac Catalyst 26.0+, tvOS 26.0+, and watchOS 26.0+. It blurs content behind it, reflects color and light from surrounding content, and reacts to touch and pointer interactions in real time. Standard SwiftUI components (tab bars, toolbars, navigation bars, sheets, popovers) adopt Liquid Glass automatically when built with the latest SDK.

This reference covers the complete API surface for applying Liquid Glass to custom views.

glassEffect(_:in:)

Applies the Liquid Glass effect behind a view.

nonisolated func glassEffect(
    _ glass: Glass = .regular,
    in shape: some Shape = DefaultGlassEffectShape()
) -> some View

The system renders a shape anchored behind the view with the Liquid Glass material and applies foreground effects over the view content. The default shape is Capsule.

Apply this modifier after other modifiers that affect the view's appearance (padding, frame, font, foregroundStyle).

Basic usage

Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect()

Custom shape

Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect(in: .rect(cornerRadius: 16.0))

Common shapes: .capsule (default), .rect(cornerRadius:), .circle.

Tinted and interactive

Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect(.regular.tint(.orange).interactive())

Use .interactive() only when the custom component is actually tappable, focusable, or otherwise interactive. For buttons, prefer the built-in glass button styles in the Button Styles section.

Glass

A structure that defines the configuration of the Liquid Glass material. Conforms to Equatable, Sendable, and SendableMetatype.

Type Properties

Instance Methods

Methods are chainable:

.glassEffect(.regular.tint(.blue).interactive())

When using .clear, verify foreground legibility over the actual background. Add a dimming layer or another contrast treatment when bright or visually busy content sits behind the glass.

ZStack {
    Capsule()
        .fill(.black.opacity(0.28))

    Label("Play", systemImage: "play.fill")
        .padding(.horizontal, 12)
        .padding(.vertical, 8)
        .glassEffect(.clear)
}
.fixedSize()

GlassEffectContainer

A view that combines multiple Liquid Glass shapes into a single rendering pass. Enables blending and morphing between individual shapes.

@MainActor @preconcurrency
struct GlassEffectContainer<Content> where Content : View

Conforms to View, Sendable, SendableMetatype.

Initializer

init(spacing: CGFloat? = nil, @ContentBuilder content: () -> Content)

The spacing parameter controls how glass shapes interact:

• Larger spacing: Shapes begin blending at greater distances; morphing starts sooner.
• Smaller spacing: Shapes must be closer before blending occurs.

Match the container spacing to the interior layout spacing so shapes remain separate at rest but merge during animated transitions.

Example

GlassEffectContainer(spacing: 40.0) {
    HStack(spacing: 40.0) {
        Image(systemName: "scribble.variable")
            .frame(width: 80.0, height: 80.0)
            .font(.system(size: 36))
            .glassEffect()

        Image(systemName: "eraser.fill")
            .frame(width: 80.0, height: 80.0)
            .font(.system(size: 36))
            .glassEffect()
    }
}

glassEffectID(_:in:)

Associates a stable identity with a Liquid Glass effect for morphing during view hierarchy transitions.

nonisolated func glassEffectID(
    _ id: (some Hashable & Sendable)?,
    in namespace: Namespace.ID
) -> some View

Use with @Namespace, GlassEffectContainer, and withAnimation to animate shapes morphing into each other when views appear or disappear.

Morphing example

@State private var isExpanded = false
@Namespace private var namespace

var body: some View {
    GlassEffectContainer(spacing: 40.0) {
        HStack(spacing: 40.0) {
            Image(systemName: "scribble.variable")
                .frame(width: 80.0, height: 80.0)
                .font(.system(size: 36))
                .glassEffect()
                .glassEffectID("pencil", in: namespace)

            if isExpanded {
                Image(systemName: "eraser.fill")
                    .frame(width: 80.0, height: 80.0)
                    .font(.system(size: 36))
                    .glassEffect()
                    .glassEffectID("eraser", in: namespace)
                    .glassEffectTransition(.matchedGeometry)
            }
        }
    }

    Button("Toggle") {
        withAnimation {
            isExpanded.toggle()
        }
    }
    .buttonStyle(.glass)
}

glassEffectUnion(id:namespace:)

Merges multiple views into a single Liquid Glass shape. All effects with the same shape, Glass variant, and union ID combine into one rendered shape.

@MainActor @preconcurrency func glassEffectUnion(
    id: (some Hashable & Sendable)?,
    namespace: Namespace.ID
) -> some View

Useful for dynamically created views or views outside a shared layout container.

Example

@Namespace private var namespace
let symbols = ["cloud.bolt.rain.fill", "sun.rain.fill", "moon.stars.fill", "moon.fill"]

GlassEffectContainer(spacing: 20.0) {
    HStack(spacing: 20.0) {
        ForEach(symbols.indices, id: \.self) { i in
            Image(systemName: symbols[i])
                .frame(width: 80.0, height: 80.0)
                .font(.system(size: 36))
                .glassEffect()
                .glassEffectUnion(id: i < 2 ? "weather" : "night", namespace: namespace)
        }
    }
}

glassEffectTransition(_:)

Controls how a glass effect appears or disappears during view hierarchy changes.

@MainActor @preconcurrency func glassEffectTransition(
    _ transition: GlassEffectTransition
) -> some View

Attach this modifier to the view whose glass effect is inserted or removed. Keep GlassEffectContainer around the related group to define the blending/morphing scope, but do not put the transition only on the always-present container.

GlassEffectTransition

A structure describing changes when a glass effect is added to or removed from the view hierarchy. Conforms to Sendable and SendableMetatype.

Type Properties

Example with explicit transition

if isExpanded {
    Image(systemName: "note")
        .frame(width: 20, height: 20)
        .glassEffect()
        .glassEffectID("note", in: namespace)
        .glassEffectTransition(.materialize)
}

Button Styles

SwiftUI provides built-in Liquid Glass button styles plus a configurable style that accepts a Glass value.

GlassButtonStyle

Standard glass appearance for buttons.

Button("Action") { }
    .buttonStyle(.glass)

GlassProminentButtonStyle

A more prominent glass appearance for primary actions.

Button("Confirm") { }
    .buttonStyle(.glassProminent)

Configurable Glass Button Style

Use .glass(_:) when a button needs a specific Glass variant or tint:

Button("Media") { }
    .buttonStyle(.glass(.clear))

When the button sits over a bright or visually busy background, include a contrast treatment underneath the clear glass or choose a more opaque style:

ZStack {
    Capsule()
        .fill(.black.opacity(0.28))

    Button {
        playRecap()
    } label: {
        Label("Play", systemImage: "play.fill")
            .font(.headline)
            .padding(.horizontal, 8)
    }
    .buttonStyle(.glass(.clear))
}
.fixedSize()

Use .glass(.regular.tint(color)) for tinted tool controls. Reserve .glassProminent for high-emphasis primary actions rather than using it as the default answer whenever a button needs visual weight.

These button styles automatically include interactivity (touch/pointer reactions). Prefer these over manually applying .glassEffect(.regular.interactive()) to buttons.

DefaultGlassEffectShape

The default shape used by glassEffect(_:in:) when no shape is specified. Resolves to Capsule.

Scroll Edge Effect

Configures the scroll edge effect style for scroll views within a view hierarchy.

nonisolated func scrollEdgeEffectStyle(
    _ style: ScrollEdgeEffectStyle?,
    for edges: Edge.Set
) -> some View

Available styles include .soft (soft edge) and .hard. System bars adopt this automatically. Apply to custom bars that float over scrollable content.

.scrollEdgeEffectStyle(.soft, for: .top)

Background Extension (Split Views)

Extend content visually under sidebars and inspectors by duplicating the view into mirrored copies with a blur effect applied on top:

NavigationSplitView {
    // sidebar content
} detail: {
    ZStack {
        BannerView()
            .backgroundExtensionEffect()
    }
}

Also available as backgroundExtensionEffect(isEnabled:) for conditional use. Apply with discretion — typically to a single background view in the detail column.

Availability Gating

All Liquid Glass APIs require iOS 26.0+. Always provide a fallback:

if #available(iOS 26, *) {
    content
        .padding()
        .glassEffect(.regular, in: .rect(cornerRadius: 16))
} else {
    content
        .padding()
        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
}

Performance Guidelines

• Use GlassEffectContainer to batch multiple glass effects into a single render pass.
• Limit the total number of glass effects visible on screen at once.
• Avoid creating many separate GlassEffectContainer instances when one can suffice.
• Profile with Instruments to check rendering performance.

Accessibility Considerations

• Test with Reduce Transparency enabled (glass effects adapt automatically for

standard components; verify custom implementations).

• Test with Reduce Motion enabled (morphing and fluid animations are simplified).
• Ensure sufficient contrast for text and icons rendered over glass; clear glass may

need a dimming layer or another contrast treatment.

• Standard components from SwiftUI adapt to these settings automatically.

Best Practices Summary

1. Use GlassEffectContainer when multiple glass views coexist. 2. Apply .glassEffect() after layout and appearance modifiers. 3. Match container spacing to interior layout spacing. 4. Use .interactive() only on tappable/focusable elements. 5. Use withAnimation when toggling views with glassEffectID for morphing. 6. Prefer .buttonStyle(.glass), .buttonStyle(.glassProminent), or configurable styles such as .buttonStyle(.glass(.clear)) for buttons. 7. Avoid overusing Liquid Glass -- reserve it for key functional elements. 8. Always gate with if #available(iOS 26, *) and provide fallback UI. 9. Test with Reduce Transparency and Reduce Motion accessibility settings. 10. Apply glassEffectTransition(_:) to the conditional glass view that appears or disappears.

Apple Documentation Links

• Applying Liquid Glass to custom views
• Adopting Liquid Glass
• Landmarks: Building an app with Liquid Glass
• View.glassEffect(_:in:))
• Glass
• GlassEffectContainer
• GlassEffectTransition
• GlassButtonStyle
• GlassProminentButtonStyle