1# SwiftUI Liquid Glass Reference (iOS 26+)
2 
3## Table of Contents
4 
5- [Overview](#overview)
6- [Availability](#availability)
7- [Core APIs](#core-apis)
8- [GlassEffectContainer](#glasseffectcontainer)
9- [Glass Button Styles](#glass-button-styles)
10- [Morphing Transitions](#morphing-transitions)
11- [Modifier Order](#modifier-order)
12- [Complete Examples](#complete-examples)
13- [Fallback Strategies](#fallback-strategies)
14- [Design System Notes](#design-system-notes)
15- [Best Practices](#best-practices)
16- [Checklist](#checklist)
17 
18## Overview
19 
20Liquid Glass is Apple's new design language introduced in iOS 26. It provides translucent, dynamic surfaces that respond to content and user interaction. This reference covers the native SwiftUI APIs for implementing Liquid Glass effects.
21 
22**Only adopt Liquid Glass when explicitly requested by the user.** Do not proactively convert existing UI to glass effects.
23 
24## Availability
25 
26All Liquid Glass APIs require iOS 26 or later. Always provide fallbacks:
27 
28```swift
29if #available(iOS 26, *) {
30    // Liquid Glass implementation
31} else {
32    // Fallback using materials
33}
34```
35 
36## Core APIs
37 
38### glassEffect Modifier
39 
40The primary modifier for applying glass effects to views:
41 
42```swift
43.glassEffect(_ glass: Glass = .regular, in shape: some Shape = .rect, isEnabled: Bool = true)
44```
45 
46#### Basic Usage
47 
48```swift
49Text("Hello")
50    .padding()
51    .glassEffect()  // Default regular style, rect shape
52```
53 
54#### With Shape
55 
56```swift
57Text("Rounded Glass")
58    .padding()
59    .glassEffect(in: .rect(cornerRadius: 16))
60 
61Image(systemName: "star")
62    .padding()
63    .glassEffect(in: .circle)
64 
65Text("Capsule")
66    .padding(.horizontal, 20)
67    .padding(.vertical, 10)
68    .glassEffect(in: .capsule)
69```
70 
71### Glass
72 
73#### Available Styles
74 
75The `Glass` type exposes three static values — there is no `.prominent`:
76 
77```swift
78.glassEffect(.regular)   // Standard glass appearance (most common)
79.glassEffect(.clear)     // Nearly invisible glass surface
80.glassEffect(.identity)  // No-op / pass-through glass
81```
82 
83To make a surface appear more prominent, increase the tint opacity instead of reaching for a non-existent `.prominent` property.
84 
85#### Tinting
86 
87Add color tint to the glass:
88 
89```swift
90.glassEffect(.regular.tint(.blue))
91.glassEffect(.regular.tint(.red.opacity(0.3)))
92```
93 
94#### Interactivity
95 
96Make glass respond to touch/pointer hover:
97 
98```swift
99// Interactive glass - responds to user interaction
100.glassEffect(.regular.interactive())
101 
102// Combined with tint
103.glassEffect(.regular.tint(.blue).interactive())
104```
105 
106**Important**: Only use `.interactive()` on elements that actually respond to user input (buttons, tappable views, focusable elements).
107 
108## GlassEffectContainer
109 
110Wraps multiple glass elements for proper visual grouping and spacing.
111 
112**Glass cannot sample other glass.** The glass material reflects and refracts light by sampling content from an area larger than itself. Nearby glass elements in different containers will produce inconsistent visual results because they cannot sample each other. `GlassEffectContainer` gives grouped elements a shared sampling region, ensuring a consistent appearance.
113 
114```swift
115GlassEffectContainer {
116    HStack {
117        Button("One") { }
118            .glassEffect()
119        Button("Two") { }
120            .glassEffect()
121    }
122}
123```
124 
125### With Spacing
126 
127Control the visual spacing between glass elements:
128 
129```swift
130GlassEffectContainer(spacing: 24) {
131    HStack(spacing: 24) {
132        GlassChip(icon: "pencil")
133        GlassChip(icon: "eraser")
134        GlassChip(icon: "trash")
135    }
136}
137```
138 
139**Note**: The container's `spacing` parameter should match the actual spacing in your layout for proper glass effect rendering.
140 
141> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
142 
143## Glass Button Styles
144 
145Built-in button styles for glass appearance:
146 
147```swift
148// Standard glass button
149Button("Action") { }
150    .buttonStyle(.glass)
151 
152// Prominent glass button (higher visibility)
153Button("Primary Action") { }
154    .buttonStyle(.glassProminent)
155```
156 
157### Custom Glass Buttons
158 
159For more control, apply glass effect manually:
160 
161```swift
162Button(action: { }) {
163    Label("Settings", systemImage: "gear")
164        .padding()
165}
166.glassEffect(.regular.interactive(), in: .capsule)
167```
168 
169## Morphing Transitions
170 
171Create smooth transitions between glass elements using `glassEffectID` and `@Namespace`:
172 
173```swift
174struct MorphingExample: View {
175    @Namespace private var animation
176    @State private var isExpanded = false
177 
178    var body: some View {
179        GlassEffectContainer {
180            if isExpanded {
181                ExpandedCard()
182                    .glassEffect()
183                    .glassEffectID("card", in: animation)
184            } else {
185                CompactCard()
186                    .glassEffect()
187                    .glassEffectID("card", in: animation)
188            }
189        }
190        .animation(.smooth, value: isExpanded)
191    }
192}
193```
194 
195### Requirements for Morphing
196 
1971. Both views must have the same `glassEffectID`
1982. Use the same `@Namespace`
1993. Wrap in `GlassEffectContainer`
2004. Apply animation to the container or parent
201 
202## Modifier Order
203 
204**Critical**: Apply `glassEffect` after layout and visual modifiers:
205 
206```swift
207// CORRECT order
208Text("Label")
209    .font(.headline)           // 1. Typography
210    .foregroundStyle(.primary) // 2. Color
211    .padding()                 // 3. Layout
212    .glassEffect()             // 4. Glass effect LAST
213 
214// WRONG order - glass applied too early
215Text("Label")
216    .glassEffect()             // Wrong position
217    .padding()
218    .font(.headline)
219```
220 
221## Complete Examples
222 
223### Toolbar with Glass Buttons
224 
225```swift
226struct GlassToolbar: View {
227    var body: some View {
228        if #available(iOS 26, *) {
229            GlassEffectContainer(spacing: 16) {
230                HStack(spacing: 16) {
231                    ToolbarButton(icon: "pencil", action: { })
232                    ToolbarButton(icon: "eraser", action: { })
233                    ToolbarButton(icon: "scissors", action: { })
234                    Spacer()
235                    ToolbarButton(icon: "square.and.arrow.up", action: { })
236                }
237                .padding(.horizontal)
238            }
239        } else {
240            // Fallback toolbar
241            HStack(spacing: 16) {
242                // ... fallback implementation
243            }
244        }
245    }
246}
247 
248struct ToolbarButton: View {
249    let icon: String
250    let action: () -> Void
251 
252    var body: some View {
253        Button(action: action) {
254            Image(systemName: icon)
255                .font(.title2)
256                .frame(width: 44, height: 44)
257        }
258        .glassEffect(.regular.interactive(), in: .circle)
259    }
260}
261```
262 
263### Card with Glass Effect
264 
265```swift
266struct GlassCard: View {
267    let title: String
268    let subtitle: String
269 
270    var body: some View {
271        if #available(iOS 26, *) {
272            cardContent
273                .glassEffect(.regular, in: .rect(cornerRadius: 20))
274        } else {
275            cardContent
276                .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 20))
277        }
278    }
279 
280    private var cardContent: some View {
281        VStack(alignment: .leading, spacing: 8) {
282            Text(title)
283                .font(.headline)
284            Text(subtitle)
285                .font(.subheadline)
286                .foregroundStyle(.secondary)
287        }
288        .padding()
289        .frame(maxWidth: .infinity, alignment: .leading)
290    }
291}
292```
293 
294### Segmented Control
295 
296```swift
297struct GlassSegmentedControl: View {
298    @Binding var selection: Int
299    let options: [String]
300    @Namespace private var animation
301 
302    var body: some View {
303        if #available(iOS 26, *) {
304            GlassEffectContainer(spacing: 4) {
305                HStack(spacing: 4) {
306                    ForEach(options.indices, id: \.self) { index in
307                        Button(options[index]) {
308                            withAnimation(.smooth) {
309                                selection = index
310                            }
311                        }
312                        .padding(.horizontal, 16)
313                        .padding(.vertical, 8)
314                        .glassEffect(
315                            selection == index
316                                ? .regular.tint(.accentColor.opacity(0.4)).interactive()
317                                : .regular.interactive(),
318                            in: .capsule
319                        )
320                        .glassEffectID(selection == index ? "selected" : "option\(index)", in: animation)
321                    }
322                }
323                .padding(4)
324            }
325        } else {
326            Picker("Options", selection: $selection) {
327                ForEach(options.indices, id: \.self) { index in
328                    Text(options[index]).tag(index)
329                }
330            }
331            .pickerStyle(.segmented)
332        }
333    }
334}
335```
336 
337## Fallback Strategies
338 
339### Using Materials
340 
341```swift
342if #available(iOS 26, *) {
343    content.glassEffect()
344} else {
345    content.background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
346}
347```
348 
349### Available Materials for Fallback
350 
351- `.ultraThinMaterial` - Closest to glass appearance
352- `.thinMaterial` - Slightly more opaque
353- `.regularMaterial` - Standard blur
354- `.thickMaterial` - More opaque
355- `.ultraThickMaterial` - Most opaque
356 
357### Conditional Modifier Extension
358 
359```swift
360extension View {
361    @ViewBuilder
362    func glassEffectWithFallback(
363        _ glass: Glass = .regular,
364        in shape: some Shape = .rect,
365        fallbackMaterial: Material = .ultraThinMaterial
366    ) -> some View {
367        if #available(iOS 26, *) {
368            self.glassEffect(glass, in: shape)
369        } else {
370            self.background(fallbackMaterial, in: shape)
371        }
372    }
373}
374```
375 
376## Design System Notes
377 
378### Toolbar Icons
379 
380In the new design, toolbar icons use **monochrome rendering** by default. The monochrome palette reduces visual noise and maintains legibility. Use `tint(_:)` only to convey meaning (e.g., a call to action), not for visual effect.
381 
382### Sheet Presentations
383 
384Partial-height sheets use a Liquid Glass background by default. If you previously used `presentationBackground(_:)` with a custom background, consider removing it to let the new material shine. Sheets can morph out of the glass controls that present them using `navigationZoomTransition`.
385 
386### Scroll Edge Effects
387 
388An automatic scroll edge effect blurs and fades content under system toolbars to keep controls legible. Remove any custom background-darkening effects behind bar items, as they will interfere.
389 
390> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
391 
392## Best Practices
393 
394### Do
395 
396- Use `GlassEffectContainer` for grouped glass elements (glass cannot sample other glass)
397- Apply glass after layout modifiers
398- Use `.interactive()` only on tappable elements
399- Match container spacing with layout spacing
400- Provide material-based fallbacks for older iOS
401- Keep glass shapes consistent within a feature
402- Remove custom `presentationBackground(_:)` on sheets to use the default glass material
403 
404### Don't
405 
406- Apply glass to every element (use sparingly)
407- Use `.interactive()` on static content
408- Mix different corner radii arbitrarily
409- Forget iOS version checks
410- Apply glass before padding/frame modifiers
411- Nest `GlassEffectContainer` unnecessarily
412- Add custom darkening backgrounds behind toolbars (conflicts with scroll edge effect)
413 
414## Checklist
415 
416- [ ] `#available(iOS 26, *)` with fallback
417- [ ] `GlassEffectContainer` wraps grouped elements
418- [ ] `.glassEffect()` applied after layout modifiers
419- [ ] `.interactive()` only on user-interactable elements
420- [ ] `glassEffectID` with `@Namespace` for morphing
421- [ ] Consistent shapes and spacing across feature
422- [ ] Container spacing matches layout spacing
423- [ ] Tint opacity used instead of non-existent `.prominent` for emphasis
424