/swiftui-expert-skill

Latest SwiftUI APIs Reference

Based on a comparison of Apple's documentation using the Sosumi MCP, we found the latest recommended APIs to use.

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.

Table of Contents

• Always Use (iOS 15+)
• When Targeting iOS 16+
• When Targeting iOS 17+
• When Targeting iOS 18+
• When Targeting iOS 26+
• When Targeting iOS 27+
• When Targeting iOS 27.1+

Always Use (iOS 15+)

These APIs have been deprecated long enough that there is no reason to use the old variants.

Compact Replacements

These replacements have minimal API shape changes. Most are near-direct swaps; a few require an additional parameter or structural adjustment:

• navigationTitle(_:) instead of navigationBarTitle(_:)
• toolbar { ToolbarItem(...) } instead of navigationBarItems(...) (structural change)
• ignoresSafeArea(_:edges:) instead of edgesIgnoringSafeArea(_:)
• preferredColorScheme(_:) instead of colorScheme(_:)
• foregroundStyle(_:) instead of foregroundColor(_:) (e.g., .foregroundStyle(.primary))
• clipShape(.rect(cornerRadius:)) instead of cornerRadius()
• textInputAutocapitalization(_:) instead of autocapitalization(_:) (note: .never replaces .none)
• animation(_:value:) instead of animation(_:) (adds required value: parameter; back-deploys to iOS 13+)
• dismiss or isPresented environment values instead of PresentationMode / presentationMode
• DynamicTypeSize / dynamicTypeSize instead of ContentSizeCategory / sizeCategory
• Closure-based NavigationLink destinations instead of eager destination: values
• Direct Animatable conformance instead of AnimatableModifier (use @Animatable only when its newer availability fits)

Lists and Forms

Use trailing-closure Section initializers instead of the positional header/footer View initializers.

The single-title form is still current and should not be treated as deprecated:

// Current - single-title LocalizedStringKey initializer
Section("Settings") {
    Toggle("Notifications", isOn: .constant(true))
}

// Replacement - content/header/footer trailing-closure initializer
Section {
    Toggle("Notifications", isOn: .constant(true))
} header: {
    Text("Settings")
} footer: {
    Text("Changes apply immediately.")
}

// Deprecated/renamed - positional header/footer View arguments
Section(header: Text("Settings"), footer: Text("Changes apply immediately.")) {
    Toggle("Notifications", isOn: .constant(true))
}

Section(header: Text("Settings")) {
    Toggle("Notifications", isOn: .constant(true))
}

Section(footer: Text("Changes apply immediately.")) {
    Toggle("Notifications", isOn: .constant(true))
}

Presentation

• Always use .confirmationDialog(_:isPresented:actions:message:) instead of actionSheet(...).
• Always use .alert(_:isPresented:actions:message:) instead of alert(isPresented:content:).

Both take a title String, isPresented: Binding<Bool>, an actions builder with Button items (supporting role: .destructive / .cancel), and an optional message builder:

.alert("Delete Item?", isPresented: $showAlert) {
    Button("Delete", role: .destructive) { deleteItem() }
    Button("Cancel", role: .cancel) { }
} message: {
    Text("This action cannot be undone.")
}

Text Input

Always use onSubmit(of:_:) and focused(_:equals:) instead of TextField onEditingChanged/onCommit callbacks.

@FocusState private var isFocused: Bool

TextField("Search", text: $query)
    .focused($isFocused)
    .onSubmit { performSearch() }

Accessibility

Always use dedicated accessibility modifiers instead of the generic accessibility(...) variants. Use .accessibilityLabel(), .accessibilityValue(), .accessibilityHint(), .accessibilityAddTraits(), .accessibilityHidden() instead of .accessibility(label:), .accessibility(value:), etc.

Custom Environment / Container Values

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.

// Modern — one line replaces ~10 lines of EnvironmentKey boilerplate
extension EnvironmentValues {
    @Entry var myCustomValue: String = "Default value"
}

Styling

Always use Button instead of onTapGesture() unless you need tap location or count.

Button("Tap me") { performAction() }

// Use onTapGesture only when you need location or count
Image("photo")
    .onTapGesture(count: 2) { handleDoubleTap() }

When Targeting iOS 16+

Navigation

Use NavigationStack (or NavigationSplitView) instead of NavigationView. Value-based NavigationLink(value:) with .navigationDestination(for:) replaces destination-based links.

NavigationStack {
    List(items) { item in
        NavigationLink(value: item) { Text(item.name) }
    }
    .navigationDestination(for: Item.self) { DetailView(item: $0) }
}

Simple Renames

• tint(_:) instead of accentColor(_:)
• autocorrectionDisabled(_:) instead of disableAutocorrection(_:)

Scroll Indicators and Search Suggestions

• Replace ScrollView(..., showsIndicators:) with ScrollView(...) plus scrollIndicators(_:axes:).
• Replace searchable overloads with an inline suggestions builder by composing searchable(...) with searchSuggestions { ... }.

Clipboard

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).

PasteButton(payloadType: String.self) { strings in
    pastedText = strings.first ?? ""
}

When Targeting iOS 17+

State Management

• 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.

Events

Use onChange(of:initial:_:) or onChange(of:) { } instead of onChange(of:perform:).

The deprecated variant passes only the new value. The modern variants provide either both old and new values, or a no-parameter closure.

• No-parameter (most common): .onChange(of: value) { doSomething() }
• Old and new values: .onChange(of: value) { old, new in ... }
• With initial trigger: .onChange(of: value, initial: true) { ... }
• Deprecated: .onChange(of: value) { newValue in ... } — single-parameter closure

Sensory Feedback

Prefer sensoryFeedback(_:trigger:) and related overloads instead of UIImpactFeedbackGenerator, UISelectionFeedbackGenerator, and UINotificationFeedbackGenerator in SwiftUI views.

Attach haptics declaratively to the view that owns the state change, rather than imperatively firing UIKit generators inside button actions.

@State private var isFavorite = false

Button("Favorite", systemImage: isFavorite ? "heart.fill" : "heart") {
    isFavorite.toggle()
}
.sensoryFeedback(.selection, trigger: isFavorite)

Use the conditional overload when feedback should fire only for specific transitions:

.sensoryFeedback(.selection, trigger: phase) { old, new in
    old == .inactive || new == .expanded
}

Gestures

• MagnifyGesture instead of MagnificationGesture (access magnitude via value.magnification)
• RotateGesture instead of RotationGesture (access angle via value.rotation)

Layout

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.

Image("hero")
    .resizable()
    .containerRelativeFrame(.horizontal) { length, axis in length * 0.8 }

• visualEffect { content, geometry in ... } — position-based effects (parallax, offsets) without a GeometryReader wrapper.
• 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:

  .onGeometryChange(for: CGFloat.self) { proxy in proxy.size.height } action: { newHeight in height = newHeight }

• .coordinateSpace(.named("scroll")) instead of .coordinateSpace(name: "scroll").

Prefer overloads accepting CoordinateSpaceProtocol for SpatialTapGesture, location-aware onTapGesture, onContinuousHover, and GeometryProxy.frame(in:).

Resolve a color in the current environment before accessing Core Graphics:

let cgColor = color.resolve(in: environment).cgColor

When Targeting iOS 18+

Toolbar Visibility

Use toolbarVisibility(_:for:) instead of navigationBarHidden(_:) or the older toolbar(_:for:) visibility overload. For deployment targets below iOS 18, retain the older modifier in the fallback branch.

Use toolbarBackgroundVisibility(_:for:) instead of the toolbarBackground(_:for:) overload whose first argument is Visibility.

On iOS, prefer .topBarLeading / .topBarTrailing over .navigationBarLeading / .navigationBarTrailing.

Tabs

Use the Tab API instead of tabItem(_:).

TabView {
    Tab("Home", systemImage: "house") { HomeView() }
    Tab("Search", systemImage: "magnifyingglass") { SearchView() }
    Tab("Profile", systemImage: "person") { ProfileView() }
}

When using Tab(role:), all tabs must use the Tab syntax. Mixing Tab(role:) with .tabItem() causes compilation errors.

On iOS 18.4+ / macOS 15.4+, use the typed customization accessors:

• customization[section: id].tabOrder
• customization[tab: id].sidebarVisibility
• customization[section: id].resetTabOrder()

Previews

Use @Previewable for dynamic properties in previews.

// Modern (iOS 18+)
#Preview {
    @Previewable @State var isOn = false
    Toggle("Setting", isOn: $isOn)
}

When Targeting iOS 26+

For Liquid Glass APIs (glassEffect, GlassEffectContainer, glass button styles), see liquid-glass.md.

Scroll Edge Effects

Use scrollEdgeEffectStyle(_:for:) to configure scroll edge behavior.

ScrollView {
    // content
}
.scrollEdgeEffectStyle(.soft, for: .top)

Background Extension

Use backgroundExtensionEffect() for edge-extending blurred backgrounds.

Views behind a Liquid Glass sidebar can appear clipped. This modifier mirrors and blurs content outside the safe area so artwork remains visible.

Image("hero")
    .backgroundExtensionEffect()

Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)

Tab Bar

Use tabBarMinimizeBehavior(_:) to control tab bar minimization on scroll.

TabView {
    // tabs
}
.tabBarMinimizeBehavior(.onScrollDown)

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.

TabView {
    // tabs
}
.tabViewBottomAccessory {
    NowPlayingBar()
}

Use Tab(role: .search) for a dedicated search tab. The tab separates from the rest and morphs into a search field when selected.

TabView {
    Tab("Home", systemImage: "house") { HomeView() }
    Tab("Profile", systemImage: "person") { ProfileView() }
    Tab(role: .search) { SearchResultsView() }
}

Source: "What's new in SwiftUI" (WWDC25, session 256) and "Build a SwiftUI app with the new design" (WWDC25, session 323)

Toolbars

For ToolbarSpacer, shared-background visibility, badges, customization, transitions, overflow, and minimization, consult toolbar-patterns.md.

Search

Use searchToolbarBehavior(.minimize) on iOS or visionOS 26+ to opt into a minimized search button. See toolbar-patterns.md for platform availability.

Animations

Use @Animatable macro instead of manual animatableData declarations. The macro auto-synthesizes animatableData from all animatable properties. Use @AnimatableIgnored to exclude specific properties.

@Animatable
struct Wedge: Shape {
    var startAngle: Angle
    var endAngle: Angle
    @AnimatableIgnored var drawClockwise: Bool

    func path(in rect: CGRect) -> Path { /* ... */ }
}

Source: "What's new in SwiftUI" (WWDC25, session 256)

Presentations

Use navigationZoomTransition to morph sheets out of their source view. Toolbar items and buttons can serve as the transition source.

.toolbar {
    ToolbarItem {
        Button("Add", systemImage: "plus") { showSheet = true }
            .navigationTransitionSource(id: "addSheet", namespace: namespace)
    }
}
.sheet(isPresented: $showSheet) {
    AddItemView()
        .navigationTransitionDestination(id: "addSheet", namespace: namespace)
}

Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)

Controls

Use controlSize(.extraLarge) for extra-large prominent action buttons.

Button("Get Started") { }
    .buttonStyle(.borderedProminent)
    .controlSize(.extraLarge)

Use concentric corner style for buttons that match their container's corners.

Button("Confirm") { }
    .clipShape(.rect(cornerRadius: 12, style: .concentric))

Sliders now support tick marks and a neutral value.

Slider(value: $speed, in: 0.5...2.0, step: 0.25) {
    Text("Speed")
} ticks: {
    SliderTick(value: 0.6)
    SliderTick(value: 0.9)
}
.sliderNeutralValue(1.0)

Source: "Build a SwiftUI app with the new design" (WWDC25, session 323)

Rich Text

Use TextEditor with an AttributedString binding for rich text editing. Supports bold, italic, underline, strikethrough, custom fonts, foreground/background colors, paragraph styles, and Genmoji.

@State private var text: AttributedString = "Hello, world!"

var body: some View {
    TextEditor(text: $text)
}

Source: "Cook up a rich text experience in SwiftUI with AttributedString" (WWDC25, session 280)

Web Content

Use WebView to display web content. For richer interaction, create a WebPage observable model.

// Simple URL display
WebView(url: URL(string: "https://example.com")!)

// With observable model
@State private var page = WebPage()

WebView(page)
    .onAppear { page.load(URLRequest(url: myURL)) }
    .navigationTitle(page.title ?? "")

Source: "Meet WebKit for SwiftUI" (WWDC25, session 231)

Drag and Drop

Use dragContainer for multi-item drag operations. Combine with DragConfiguration for custom drag behavior and onDragSessionUpdated to observe events.

PhotoGrid(photos: photos)
    .dragContainer(for: Photo.self) { selection in
        return selection.map { $0.transferable }
    }
    .onDragSessionUpdated { session in
        if session.phase == .endedWithDelete {
            deleteSelectedPhotos()
        }
    }

Migrate the older location/isTargeted dropDestination overload to dropDestination(for:isEnabled:action:) when targeting iOS, macOS, or visionOS 26+. Its action receives a DropSession and returns Void, so this is a behavioral migration rather than a label-only rename.

Source: "What's new in SwiftUI" (WWDC25, session 256)

Scene Bridging

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:).

Source: "What's new in SwiftUI" (WWDC25, session 256)

When Targeting iOS 27+

Use the focused topic references for detailed guidance:

• state-management.md
• view-structure.md
• list-patterns.md
• image-optimization.md
• layout-best-practices.md
• sheet-navigation-patterns.md
• toolbar-patterns.md

On iOS 27+, use toolbarVisibility(_:for: .statusBar) instead of statusBarHidden(_:). ToolbarPlacement.statusBar is iOS-only; on visionOS, remove statusBarHidden because it has no effect. The newer dropDestination(for:isEnabled:action:) overload is also available on visionOS 26+ (as well as iOS/macOS 26+).

Additional SDK 27 soft-deprecated families

Use Menu / MenuStyle instead of MenuButton, MenuButtonStyle, and the legacy menu-button styles (PullDownMenuButtonStyle, BorderlessPullDownMenuButtonStyle, BorderlessButtonMenuButtonStyle, DefaultMenuButtonStyle, BorderedButtonMenuStyle, and BorderlessButtonMenuStyle). Use .menuStyle(.menu) or .menuStyle(.button) with a button style instead of PopUpButtonPickerStyle.

Other lookup entries from the SDK include:

• ContextMenu and contextMenu(_:) → contextMenu(menuItems:)
• Section(header:...)/Section(footer:...)/Section(header:footer:...) → trailing-closure Section(content:header:footer:) forms
• GroupBox(label:content:) → GroupBox(content:label:)
• Picker(selection:label:content:) → Picker(selection:content:label:)
• Color(_:) platform and CGColor initializers → Color(uiColor:), Color(nsColor:), and Color(cgColor:); Color.cgColor → resolve(in:).cgColor
• onLongPressGesture overloads with pressing: → onLongPressGesture(minimumDuration:maximumDuration:perform:onPressingChanged:) or its shorter counterpart
• Font.system(_:design:) and legacy Font.system(size:weight:design:) forms → system(_:weight:design:) and the current size/weight/design overloads
• Section.collapsible(_:) → a standard Section initializer (collapsibility is no longer enabled by that modifier)
• string-type paste/drop APIs (PasteButton, onPasteCommand, onInsert, and DropInfo.hasItemsConforming) → UTType-based APIs

Platform-specific entries include CarouselTabViewStyle → VerticalTabViewStyle and listRowPlatterColor(_:) → listItemTint(_:) on watchOS, ControlActiveState → appearsActive on macOS, and SurroundingsEffect.systemDark → .dark on visionOS.

Search this file's lookup table when migrating an API that the 27 SDK marks soft-deprecated. Do not introduce unrelated migrations during feature work; follow soft-deprecation.md.

When Targeting iOS 27.1+

• ArrangementView, .split / .overlay, and arrangement axis constraints provide adaptive two-region layout and tuning modifiers such as splitArrangementLayoutRatio. See layout-best-practices.md.
• ReservedRegion and GeometryProxy.reservedRegions(kind:options:layoutDirectionBehavior:) expose division and occlusion geometry for custom layouts. See layout-best-practices.md.
• ToolbarContent.axisBehavior(_:), toolbarVerticalEdge, toolbarVerticalCompressionBehavior(_:), and toolbarVerticalBehavior(_:) support adaptive vertical bars. See toolbar-patterns.md.
• onHingeChange and the optional DeviceHingeContext.hinge support live effects and interactions, not layout decisions. For iPhone Duo-specific use, see iphone-duo.md.

These APIs are from the beta iOS 27.1 SDK. Gate runtime use with #available(iOS 27.1, *), provide an earlier-system fallback, and recheck semantics against the shipping SDK.

Quick Lookup Table