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(_ style: GlassEffectStyle = .regular, in shape: some Shape = .rect)
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### GlassEffectStyle
72 
73#### Prominence Levels
74 
75```swift
76.glassEffect(.regular)     // Standard glass appearance
77.glassEffect(.prominent)   // More visible, higher contrast
78```
79 
80#### Tinting
81 
82Add color tint to the glass:
83 
84```swift
85.glassEffect(.regular.tint(.blue))
86.glassEffect(.prominent.tint(.red.opacity(0.3)))
87```
88 
89#### Interactivity
90 
91Make glass respond to touch/pointer hover:
92 
93```swift
94// Interactive glass - responds to user interaction
95.glassEffect(.regular.interactive())
96 
97// Combined with tint
98.glassEffect(.regular.tint(.blue).interactive())
99```
100 
101**Important**: Only use `.interactive()` on elements that actually respond to user input (buttons, tappable views, focusable elements).
102 
103## GlassEffectContainer
104 
105Wraps multiple glass elements for proper visual grouping and spacing.
106 
107**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.
108 
109```swift
110GlassEffectContainer {
111    HStack {
112        Button("One") { }
113            .glassEffect()
114        Button("Two") { }
115            .glassEffect()
116    }
117}
118```
119 
120### With Spacing
121 
122Control the visual spacing between glass elements:
123 
124```swift
125GlassEffectContainer(spacing: 24) {
126    HStack(spacing: 24) {
127        GlassChip(icon: "pencil")
128        GlassChip(icon: "eraser")
129        GlassChip(icon: "trash")
130    }
131}
132```
133 
134**Note**: The container's `spacing` parameter should match the actual spacing in your layout for proper glass effect rendering.
135 
136> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
137 
138## Glass Button Styles
139 
140Built-in button styles for glass appearance:
141 
142```swift
143// Standard glass button
144Button("Action") { }
145    .buttonStyle(.glass)
146 
147// Prominent glass button (higher visibility)
148Button("Primary Action") { }
149    .buttonStyle(.glassProminent)
150```
151 
152### Custom Glass Buttons
153 
154For more control, apply glass effect manually:
155 
156```swift
157Button(action: { }) {
158    Label("Settings", systemImage: "gear")
159        .padding()
160}
161.glassEffect(.regular.interactive(), in: .capsule)
162```
163 
164## Morphing Transitions
165 
166Create smooth transitions between glass elements using `glassEffectID` and `@Namespace`:
167 
168```swift
169struct MorphingExample: View {
170    @Namespace private var animation
171    @State private var isExpanded = false
172 
173    var body: some View {
174        GlassEffectContainer {
175            if isExpanded {
176                ExpandedCard()
177                    .glassEffect()
178                    .glassEffectID("card", in: animation)
179            } else {
180                CompactCard()
181                    .glassEffect()
182                    .glassEffectID("card", in: animation)
183            }
184        }
185        .animation(.smooth, value: isExpanded)
186    }
187}
188```
189 
190### Requirements for Morphing
191 
1921. Both views must have the same `glassEffectID`
1932. Use the same `@Namespace`
1943. Wrap in `GlassEffectContainer`
1954. Apply animation to the container or parent
196 
197## Modifier Order
198 
199**Critical**: Apply `glassEffect` after layout and visual modifiers:
200 
201```swift
202// CORRECT order
203Text("Label")
204    .font(.headline)           // 1. Typography
205    .foregroundStyle(.primary) // 2. Color
206    .padding()                 // 3. Layout
207    .glassEffect()             // 4. Glass effect LAST
208 
209// WRONG order - glass applied too early
210Text("Label")
211    .glassEffect()             // Wrong position
212    .padding()
213    .font(.headline)
214```
215 
216## Complete Examples
217 
218### Toolbar with Glass Buttons
219 
220```swift
221struct GlassToolbar: View {
222    var body: some View {
223        if #available(iOS 26, *) {
224            GlassEffectContainer(spacing: 16) {
225                HStack(spacing: 16) {
226                    ToolbarButton(icon: "pencil", action: { })
227                    ToolbarButton(icon: "eraser", action: { })
228                    ToolbarButton(icon: "scissors", action: { })
229                    Spacer()
230                    ToolbarButton(icon: "square.and.arrow.up", action: { })
231                }
232                .padding(.horizontal)
233            }
234        } else {
235            // Fallback toolbar
236            HStack(spacing: 16) {
237                // ... fallback implementation
238            }
239        }
240    }
241}
242 
243struct ToolbarButton: View {
244    let icon: String
245    let action: () -> Void
246 
247    var body: some View {
248        Button(action: action) {
249            Image(systemName: icon)
250                .font(.title2)
251                .frame(width: 44, height: 44)
252        }
253        .glassEffect(.regular.interactive(), in: .circle)
254    }
255}
256```
257 
258### Card with Glass Effect
259 
260```swift
261struct GlassCard: View {
262    let title: String
263    let subtitle: String
264 
265    var body: some View {
266        if #available(iOS 26, *) {
267            cardContent
268                .glassEffect(.regular, in: .rect(cornerRadius: 20))
269        } else {
270            cardContent
271                .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 20))
272        }
273    }
274 
275    private var cardContent: some View {
276        VStack(alignment: .leading, spacing: 8) {
277            Text(title)
278                .font(.headline)
279            Text(subtitle)
280                .font(.subheadline)
281                .foregroundStyle(.secondary)
282        }
283        .padding()
284        .frame(maxWidth: .infinity, alignment: .leading)
285    }
286}
287```
288 
289### Segmented Control
290 
291```swift
292struct GlassSegmentedControl: View {
293    @Binding var selection: Int
294    let options: [String]
295    @Namespace private var animation
296 
297    var body: some View {
298        if #available(iOS 26, *) {
299            GlassEffectContainer(spacing: 4) {
300                HStack(spacing: 4) {
301                    ForEach(options.indices, id: \.self) { index in
302                        Button(options[index]) {
303                            withAnimation(.smooth) {
304                                selection = index
305                            }
306                        }
307                        .padding(.horizontal, 16)
308                        .padding(.vertical, 8)
309                        .glassEffect(
310                            selection == index ? .prominent.interactive() : .regular.interactive(),
311                            in: .capsule
312                        )
313                        .glassEffectID(selection == index ? "selected" : "option\(index)", in: animation)
314                    }
315                }
316                .padding(4)
317            }
318        } else {
319            Picker("Options", selection: $selection) {
320                ForEach(options.indices, id: \.self) { index in
321                    Text(options[index]).tag(index)
322                }
323            }
324            .pickerStyle(.segmented)
325        }
326    }
327}
328```
329 
330## Fallback Strategies
331 
332### Using Materials
333 
334```swift
335if #available(iOS 26, *) {
336    content.glassEffect()
337} else {
338    content.background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
339}
340```
341 
342### Available Materials for Fallback
343 
344- `.ultraThinMaterial` - Closest to glass appearance
345- `.thinMaterial` - Slightly more opaque
346- `.regularMaterial` - Standard blur
347- `.thickMaterial` - More opaque
348- `.ultraThickMaterial` - Most opaque
349 
350### Conditional Modifier Extension
351 
352```swift
353extension View {
354    @ViewBuilder
355    func glassEffectWithFallback(
356        _ style: GlassEffectStyle = .regular,
357        in shape: some Shape = .rect,
358        fallbackMaterial: Material = .ultraThinMaterial
359    ) -> some View {
360        if #available(iOS 26, *) {
361            self.glassEffect(style, in: shape)
362        } else {
363            self.background(fallbackMaterial, in: shape)
364        }
365    }
366}
367```
368 
369## Design System Notes
370 
371### Toolbar Icons
372 
373In 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.
374 
375### Sheet Presentations
376 
377Partial-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`.
378 
379### Scroll Edge Effects
380 
381An 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.
382 
383> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
384 
385## Best Practices
386 
387### Do
388 
389- Use `GlassEffectContainer` for grouped glass elements (glass cannot sample other glass)
390- Apply glass after layout modifiers
391- Use `.interactive()` only on tappable elements
392- Match container spacing with layout spacing
393- Provide material-based fallbacks for older iOS
394- Keep glass shapes consistent within a feature
395- Remove custom `presentationBackground(_:)` on sheets to use the default glass material
396 
397### Don't
398 
399- Apply glass to every element (use sparingly)
400- Use `.interactive()` on static content
401- Mix different corner radii arbitrarily
402- Forget iOS version checks
403- Apply glass before padding/frame modifiers
404- Nest `GlassEffectContainer` unnecessarily
405- Add custom darkening backgrounds behind toolbars (conflicts with scroll edge effect)
406 
407## Checklist
408 
409- [ ] `#available(iOS 26, *)` with fallback
410- [ ] `GlassEffectContainer` wraps grouped elements
411- [ ] `.glassEffect()` applied after layout modifiers
412- [ ] `.interactive()` only on user-interactable elements
413- [ ] `glassEffectID` with `@Namespace` for morphing
414- [ ] Consistent shapes and spacing across feature
415- [ ] Container spacing matches layout spacing
416- [ ] Appropriate prominence levels used
417