1# Latest SwiftUI APIs Reference
2 
3> Based on a comparison of Apple's documentation using the Sosumi MCP, we found the latest recommended APIs to use.
4 
5## Table of Contents
6- [Always Use (iOS 15+)](#always-use-ios-15)
7- [When Targeting iOS 16+](#when-targeting-ios-16)
8- [When Targeting iOS 17+](#when-targeting-ios-17)
9- [When Targeting iOS 18+](#when-targeting-ios-18)
10- [When Targeting iOS 26+](#when-targeting-ios-26)
11 
12---
13 
14## Always Use (iOS 15+)
15 
16These APIs have been deprecated long enough that there is no reason to use the old variants.
17 
18### Compact Replacements
19 
20These replacements have minimal API shape changes. Most are near-direct swaps; a few require an additional parameter or structural adjustment:
21 
22- **`navigationTitle(_:)`** instead of `navigationBarTitle(_:)`
23- **`toolbar { ToolbarItem(...) }`** instead of `navigationBarItems(...)` (structural change)
24- **`toolbarVisibility(.hidden, for: .navigationBar)`** instead of `navigationBarHidden(_:)`
25- **`statusBarHidden(_:)`** instead of `statusBar(hidden:)`
26- **`ignoresSafeArea(_:edges:)`** instead of `edgesIgnoringSafeArea(_:)`
27- **`preferredColorScheme(_:)`** instead of `colorScheme(_:)`
28- **`foregroundStyle(_:)`** instead of `foregroundColor(_:)` (e.g., `.foregroundStyle(.primary)`)
29- **`clipShape(.rect(cornerRadius:))`** instead of `cornerRadius()`
30- **`textInputAutocapitalization(_:)`** instead of `autocapitalization(_:)` (note: `.never` replaces `.none`)
31- **`animation(_:value:)`** instead of `animation(_:)` (adds required `value:` parameter; back-deploys to iOS 13+)
32 
33### Presentation
34 
35- **Always use `.confirmationDialog(_:isPresented:actions:message:)`** instead of `actionSheet(...)`.
36- **Always use `.alert(_:isPresented:actions:message:)`** instead of `alert(isPresented:content:)`.
37 
38Both take a title `String`, `isPresented: Binding<Bool>`, an `actions` builder with `Button` items (supporting `role: .destructive` / `.cancel`), and an optional `message` builder:
39 
40```swift
41.alert("Delete Item?", isPresented: $showAlert) {
42    Button("Delete", role: .destructive) { deleteItem() }
43    Button("Cancel", role: .cancel) { }
44} message: {
45    Text("This action cannot be undone.")
46}
47```
48 
49### Text Input
50 
51**Always use `onSubmit(of:_:)` and `focused(_:equals:)` instead of `TextField` `onEditingChanged`/`onCommit` callbacks.**
52 
53```swift
54@FocusState private var isFocused: Bool
55 
56TextField("Search", text: $query)
57    .focused($isFocused)
58    .onSubmit { performSearch() }
59```
60 
61### Accessibility
62 
63**Always use dedicated accessibility modifiers instead of the generic `accessibility(...)` variants.** Use `.accessibilityLabel()`, `.accessibilityValue()`, `.accessibilityHint()`, `.accessibilityAddTraits()`, `.accessibilityHidden()` instead of `.accessibility(label:)`, `.accessibility(value:)`, etc.
64 
65### Custom Environment / Container Values
66 
67**Always use the `@Entry` macro instead of manual `EnvironmentKey` conformance.** The `@Entry` macro was introduced in Xcode 16 and back-deploys to all OS versions.
68 
69```swift
70// Modern — one line replaces ~10 lines of EnvironmentKey boilerplate
71extension EnvironmentValues {
72    @Entry var myCustomValue: String = "Default value"
73}
74```
75 
76### Styling
77 
78**Always use `Button` instead of `onTapGesture()` unless you need tap location or count.**
79 
80```swift
81Button("Tap me") { performAction() }
82 
83// Use onTapGesture only when you need location or count
84Image("photo")
85    .onTapGesture(count: 2) { handleDoubleTap() }
86```
87 
88---
89 
90## When Targeting iOS 16+
91 
92### Navigation
93 
94**Use `NavigationStack` (or `NavigationSplitView`) instead of `NavigationView`.** Value-based `NavigationLink(value:)` with `.navigationDestination(for:)` replaces destination-based links.
95 
96```swift
97NavigationStack {
98    List(items) { item in
99        NavigationLink(value: item) { Text(item.name) }
100    }
101    .navigationDestination(for: Item.self) { DetailView(item: $0) }
102}
103```
104 
105### Simple Renames
106 
107- **`tint(_:)`** instead of `accentColor(_:)`
108- **`autocorrectionDisabled(_:)`** instead of `disableAutocorrection(_:)`
109 
110### Clipboard
111 
112**Prefer `PasteButton` for user-initiated paste UI** to avoid paste prompts. It handles permissions automatically. Use `UIPasteboard` only when you need programmatic or non-`Transferable` clipboard access (triggers the paste permission prompt).
113 
114```swift
115PasteButton(payloadType: String.self) { strings in
116    pastedText = strings.first ?? ""
117}
118```
119 
120---
121 
122## When Targeting iOS 17+
123 
124### State Management
125 
126- **Prefer `@Observable` over `ObservableObject` for new code.** Use `@State` instead of `@StateObject`; use `@Bindable` instead of `@ObservedObject`. See `state-management.md` for full `@Observable` migration patterns.
127 
128### Events
129 
130**Use `onChange(of:initial:_:)` or `onChange(of:) { }` instead of `onChange(of:perform:)`.**
131 
132The deprecated variant passes only the new value. The modern variants provide either both old and new values, or a no-parameter closure.
133 
134- **No-parameter** (most common): `.onChange(of: value) { doSomething() }`
135- **Old and new values**: `.onChange(of: value) { old, new in ... }`
136- **With initial trigger**: `.onChange(of: value, initial: true) { ... }`
137- **Deprecated**: `.onChange(of: value) { newValue in ... }` — single-parameter closure
138 
139### Sensory Feedback
140 
141**Prefer `sensoryFeedback(_:trigger:)` and related overloads instead of `UIImpactFeedbackGenerator`, `UISelectionFeedbackGenerator`, and `UINotificationFeedbackGenerator` in SwiftUI views.**
142 
143Attach haptics declaratively to the view that owns the state change, rather than imperatively firing UIKit generators inside button actions.
144 
145```swift
146@State private var isFavorite = false
147 
148Button("Favorite", systemImage: isFavorite ? "heart.fill" : "heart") {
149    isFavorite.toggle()
150}
151.sensoryFeedback(.selection, trigger: isFavorite)
152```
153 
154Use the conditional overload when feedback should fire only for specific transitions:
155 
156```swift
157.sensoryFeedback(.selection, trigger: phase) { old, new in
158    old == .inactive || new == .expanded
159}
160```
161 
162### Gestures
163 
164- **`MagnifyGesture`** instead of `MagnificationGesture` (access magnitude via `value.magnification`)
165- **`RotateGesture`** instead of `RotationGesture` (access angle via `value.rotation`)
166 
167### Layout
168 
169**Consider `containerRelativeFrame()` or `visualEffect()` as alternatives to `GeometryReader` for sizing and position-based effects.** `GeometryReader` is not deprecated and remains necessary for many measurement-based layouts.
170 
171```swift
172Image("hero")
173    .resizable()
174    .containerRelativeFrame(.horizontal) { length, axis in length * 0.8 }
175```
176 
177- **`visualEffect { content, geometry in ... }`** — position-based effects (parallax, offsets) without a `GeometryReader` wrapper.
178- **`onGeometryChange(for:of:action:)`** — react to geometry changes of a specific view; useful for driving state/effects. `GeometryReader` is still better when layout itself depends on geometry. Note the two-closure shape:
179  ```swift
180  .onGeometryChange(for: CGFloat.self) { proxy in proxy.size.height } action: { newHeight in height = newHeight }
181  ```
182- **`.coordinateSpace(.named("scroll"))`** instead of `.coordinateSpace(name: "scroll")`.
183 
184---
185 
186## When Targeting iOS 18+
187 
188### Tabs
189 
190**Use the `Tab` API instead of `tabItem(_:)`.**
191 
192```swift
193TabView {
194    Tab("Home", systemImage: "house") { HomeView() }
195    Tab("Search", systemImage: "magnifyingglass") { SearchView() }
196    Tab("Profile", systemImage: "person") { ProfileView() }
197}
198```
199 
200When using `Tab(role:)`, all tabs must use the `Tab` syntax. Mixing `Tab(role:)` with `.tabItem()` causes compilation errors.
201 
202### Previews
203 
204**Use `@Previewable` for dynamic properties in previews.**
205 
206```swift
207// Modern (iOS 18+)
208#Preview {
209    @Previewable @State var isOn = false
210    Toggle("Setting", isOn: $isOn)
211}
212```
213 
214---
215 
216## When Targeting iOS 26+
217 
218For Liquid Glass APIs (`glassEffect`, `GlassEffectContainer`, glass button styles), see [liquid-glass.md](liquid-glass.md).
219 
220### Scroll Edge Effects
221 
222**Use `scrollEdgeEffectStyle(_:for:)` to configure scroll edge behavior.**
223 
224```swift
225ScrollView {
226    // content
227}
228.scrollEdgeEffectStyle(.soft, for: .top)
229```
230 
231### Background Extension
232 
233**Use `backgroundExtensionEffect()` for edge-extending blurred backgrounds.**
234 
235Views behind a Liquid Glass sidebar can appear clipped. This modifier mirrors and blurs content outside the safe area so artwork remains visible.
236 
237```swift
238Image("hero")
239    .backgroundExtensionEffect()
240```
241 
242> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
243 
244### Tab Bar
245 
246**Use `tabBarMinimizeBehavior(_:)` to control tab bar minimization on scroll.**
247 
248```swift
249TabView {
250    // tabs
251}
252.tabBarMinimizeBehavior(.onScrollDown)
253```
254 
255**Use `tabViewBottomAccessory` for persistent controls above the tab bar.** Read `tabViewBottomAccessoryPlacement` from the environment to adapt content when the accessory collapses into the tab bar area.
256 
257```swift
258TabView {
259    // tabs
260}
261.tabViewBottomAccessory {
262    NowPlayingBar()
263}
264```
265 
266**Use `Tab(role: .search)` for a dedicated search tab.** The tab separates from the rest and morphs into a search field when selected.
267 
268```swift
269TabView {
270    Tab("Home", systemImage: "house") { HomeView() }
271    Tab("Profile", systemImage: "person") { ProfileView() }
272    Tab(role: .search) { SearchResultsView() }
273}
274```
275 
276> Source: "What's new in SwiftUI" (WWDC25, session 256) and "Build a SwiftUI app with the new design" (WWDC25, session 323)
277 
278### Toolbars
279 
280**Use `ToolbarSpacer` to control grouping of toolbar items.** Fixed spacers visually separate related groups; flexible spacers push items apart.
281 
282```swift
283.toolbar {
284    ToolbarItem(placement: .topBarTrailing) {
285        Button("Up", systemImage: "chevron.up") { }
286    }
287    ToolbarItem(placement: .topBarTrailing) {
288        Button("Down", systemImage: "chevron.down") { }
289    }
290    ToolbarSpacer(.fixed)
291    ToolbarItem(placement: .topBarTrailing) {
292        Button("Settings", systemImage: "gear") { }
293    }
294}
295```
296 
297**Use `sharedBackgroundVisibility(.hidden)` to remove the glass group background from an individual toolbar item.**
298 
299```swift
300ToolbarItem(placement: .topBarTrailing) {
301    Image(systemName: "person.circle.fill")
302        .sharedBackgroundVisibility(.hidden)
303}
304```
305 
306**Use `badge(_:)` on toolbar item content to display an indicator.**
307 
308```swift
309ToolbarItem(placement: .topBarTrailing) {
310    Button("Notifications", systemImage: "bell") { }
311        .badge(unreadCount)
312}
313```
314 
315> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
316 
317### Search
318 
319**Use `searchToolbarBehavior(.minimizable)` to opt into a minimized search button.** The system may automatically minimize search into a toolbar button depending on available space. Use this modifier to explicitly opt in.
320 
321```swift
322NavigationStack {
323    ContentView()
324        .searchable(text: $query)
325        .searchToolbarBehavior(.minimizable)
326}
327```
328 
329> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
330 
331### Animations
332 
333**Use `@Animatable` macro instead of manual `animatableData` declarations.** The macro auto-synthesizes `animatableData` from all animatable properties. Use `@AnimatableIgnored` to exclude specific properties.
334 
335```swift
336@Animatable
337struct Wedge: Shape {
338    var startAngle: Angle
339    var endAngle: Angle
340    @AnimatableIgnored var drawClockwise: Bool
341 
342    func path(in rect: CGRect) -> Path { /* ... */ }
343}
344```
345 
346> Source: "What's new in SwiftUI" (WWDC25, session 256)
347 
348### Presentations
349 
350**Use `navigationZoomTransition` to morph sheets out of their source view.** Toolbar items and buttons can serve as the transition source.
351 
352```swift
353.toolbar {
354    ToolbarItem {
355        Button("Add", systemImage: "plus") { showSheet = true }
356            .navigationTransitionSource(id: "addSheet", namespace: namespace)
357    }
358}
359.sheet(isPresented: $showSheet) {
360    AddItemView()
361        .navigationTransitionDestination(id: "addSheet", namespace: namespace)
362}
363```
364 
365> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
366 
367### Controls
368 
369**Use `controlSize(.extraLarge)` for extra-large prominent action buttons.**
370 
371```swift
372Button("Get Started") { }
373    .buttonStyle(.borderedProminent)
374    .controlSize(.extraLarge)
375```
376 
377**Use `concentric` corner style for buttons that match their container's corners.**
378 
379```swift
380Button("Confirm") { }
381    .clipShape(.rect(cornerRadius: 12, style: .concentric))
382```
383 
384**Sliders now support tick marks and a neutral value.**
385 
386```swift
387Slider(value: $speed, in: 0.5...2.0, step: 0.25) {
388    Text("Speed")
389} ticks: {
390    SliderTick(value: 0.6)
391    SliderTick(value: 0.9)
392}
393.sliderNeutralValue(1.0)
394```
395 
396> Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)
397 
398### Rich Text
399 
400**Use `TextEditor` with an `AttributedString` binding for rich text editing.** Supports bold, italic, underline, strikethrough, custom fonts, foreground/background colors, paragraph styles, and Genmoji.
401 
402```swift
403@State private var text: AttributedString = "Hello, world!"
404 
405var body: some View {
406    TextEditor(text: $text)
407}
408```
409 
410> Source: "Cook up a rich text experience in SwiftUI with AttributedString" (WWDC25, session 280)
411 
412### Web Content
413 
414**Use `WebView` to display web content.** For richer interaction, create a `WebPage` observable model.
415 
416```swift
417// Simple URL display
418WebView(url: URL(string: "https://example.com")!)
419 
420// With observable model
421@State private var page = WebPage()
422 
423WebView(page)
424    .onAppear { page.load(URLRequest(url: myURL)) }
425    .navigationTitle(page.title ?? "")
426```
427 
428> Source: "Meet WebKit for SwiftUI" (WWDC25, session 231)
429 
430### Drag and Drop
431 
432**Use `dragContainer` for multi-item drag operations.** Combine with `DragConfiguration` for custom drag behavior and `onDragSessionUpdated` to observe events.
433 
434```swift
435PhotoGrid(photos: photos)
436    .dragContainer(for: Photo.self) { selection in
437        return selection.map { $0.transferable }
438    }
439    .onDragSessionUpdated { session in
440        if session.phase == .endedWithDelete {
441            deleteSelectedPhotos()
442        }
443    }
444```
445 
446> Source: "What's new in SwiftUI" (WWDC25, session 256)
447 
448### Scene Bridging
449 
450**UIKit and AppKit lifecycle apps can now request SwiftUI scenes.** This enables using SwiftUI-only scene types like `MenuBarExtra` and `ImmersiveSpace` from imperative lifecycle apps via `UIApplication.shared.activateSceneSession(for:errorHandler:)`.
451 
452> Source: "What's new in SwiftUI" (WWDC25, session 256)
453 
454---
455 
456## Quick Lookup Table
457 
458| Deprecated | Recommended | Since |
459|-----------|-------------|-------|
460| `navigationBarTitle(_:)` | `navigationTitle(_:)` | iOS 15+ |
461| `navigationBarItems(...)` | `toolbar { ToolbarItem(...) }` | iOS 15+ |
462| `navigationBarHidden(_:)` | `toolbarVisibility(.hidden, for: .navigationBar)` | iOS 15+ |
463| `statusBar(hidden:)` | `statusBarHidden(_:)` | iOS 15+ |
464| `edgesIgnoringSafeArea(_:)` | `ignoresSafeArea(_:edges:)` | iOS 15+ |
465| `colorScheme(_:)` | `preferredColorScheme(_:)` | iOS 15+ |
466| `foregroundColor(_:)` | `foregroundStyle(_:)` | iOS 15+ |
467| `cornerRadius(_:)` | `clipShape(.rect(cornerRadius:))` | iOS 15+ |
468| `actionSheet(...)` | `confirmationDialog(...)` | iOS 15+ |
469| `alert(isPresented:content:)` | `alert(_:isPresented:actions:message:)` | iOS 15+ |
470| `autocapitalization(_:)` | `textInputAutocapitalization(_:)` | iOS 15+ |
471| `accessibility(label:)` etc. | `accessibilityLabel()` etc. | iOS 15+ |
472| `TextField` `onCommit`/`onEditingChanged` | `onSubmit` + `focused` | iOS 15+ |
473| `animation(_:)` (no value) | `animation(_:value:)` | Back-deploys (iOS 13+) |
474| Manual `EnvironmentKey` | `@Entry` macro | Back-deploys (Xcode 16+) |
475| `NavigationView` | `NavigationStack` / `NavigationSplitView` | iOS 16+ |
476| `accentColor(_:)` | `tint(_:)` | iOS 16+ |
477| `disableAutocorrection(_:)` | `autocorrectionDisabled(_:)` | iOS 16+ |
478| `UIPasteboard.general` | `PasteButton` | iOS 16+ |
479| `onChange(of:perform:)` | `onChange(of:) { }` or `onChange(of:) { old, new in }` | iOS 17+ |
480| `UIImpactFeedbackGenerator` / `UISelectionFeedbackGenerator` / `UINotificationFeedbackGenerator` | `sensoryFeedback(_:trigger:)` | iOS 17+ |
481| `MagnificationGesture` | `MagnifyGesture` | iOS 17+ |
482| `RotationGesture` | `RotateGesture` | iOS 17+ |
483| `coordinateSpace(name:)` | `coordinateSpace(.named(...))` | iOS 17+ |
484| `ObservableObject` | `@Observable` | iOS 17+ |
485| `tabItem(_:)` | `Tab` API | iOS 18+ |
486| Manual `animatableData` | `@Animatable` macro | iOS 26+ |
487| `presentationBackground(_:)` on sheets | Default Liquid Glass sheet material | iOS 26+ |
488| Custom toolbar background hacks | `scrollEdgeEffectStyle(_:for:)` | iOS 26+ |
489