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