What's New in SwiftUI for iOS 27

Every SwiftUI release tells you where the framework’s pressure points were by what Apple decided to rebuild. iOS 27’s answer is unusually broad: lists get first-class reordering, documents get a new reader/writer protocol family, toolbars get an overflow model with explicit priority, and error presentation finally gets a binding you can hand an Error directly. The release moves four surfaces at once, and most apps touch at least two of them.¹

The temptation with a release this wide is to adopt everything. The better move is to recognize which additions change how you build versus which are convenience overloads on patterns you already use. Drag-to-reorder and the document protocols are the former: they replace code you wrote by hand. Item-based alerts and AsyncImage(request:) are the latter: they remove a workaround. This post sorts the iOS 27 SwiftUI surface into those threads, with the real declarations and the reasoning for when each one earns its place in your code.

Apple’s UI Frameworks team frames the iOS 27 SwiftUI release around four pressure points at once: refined look and feel, document APIs, new interactions, and performance.

In session 269, Apple frames the release as four broad threads moving together, a refined look and feel, a powerful new document API, new ways to interact, and performance work, rather than a single headline feature.³⁵

TL;DR / Key Takeaways

• Lists and custom containers get declarative reordering: reorderContainer(for:isEnabled:move:) marks a container, reorderable() on DynamicViewContent opts the rows in, and you receive a ReorderDifference instead of writing index-math by hand.²³
• Lazy drag containers arrive through dragContainer(for:itemID:in:_:) plus draggable(containerItemID:containerNamespace:), which carries only an identifier so the framework fetches payloads lazily when a drag starts.⁴⁵
• A new document model lands as ReadableDocument and WritableDocument (with DocumentReader/DocumentWriter doing the on-disk work and FileWrapperDocumentReader/FileWrapperDocumentWriter for the simple case), backed by URLDocumentConfiguration.^6789101112
• Toolbars gain ToolbarOverflowMenu, the topBarPinnedTrailing placement, and visibilityPriority(_:), so you decide which controls survive when the bar runs out of room.¹³¹⁴¹⁵
• Error presentation gets alert(error:actions:message:) and item-based alert(_:item:actions:) / confirmationDialog, plus AsyncImage(request:) for full URLRequest control and asyncImageURLSession(_:) to share a session.^1617181920
• Rounding out the surface: swipeActions(...onPresentationChanged:), swipeActionsContainer(), NavigationTransition.crossFade, TabRole.prominent, UIHostingSceneDelegate, and GestureInputKinds.^212223242526

Drag-To-Reorder Becomes Declarative

Reordering a list in SwiftUI used to mean onMove, an index set, and a destination offset you translated into your own model mutation. iOS 27 replaces that with a two-part declaration: you mark a container as reorderable, and you mark its content as participating. The container then hands you a structured diff.

The single-collection case is the common one. You declare reorderContainer(for:isEnabled:move:) on the container and reorderable() on the DynamicViewContent inside it:²³

struct LandmarkList: View {
    @State private var landmarks: [Landmark]

    var body: some View {
        List {
            ForEach(landmarks) { landmark in
                LandmarkRow(landmark: landmark)
            }
            .reorderable()
        }
        .reorderContainer(for: Landmark.self) { difference in
            // Apply the reorder to your model.
            landmarks.apply(difference)
        }
    }
}

The signature tells you the contract. The container modifier is generic over Item : Identifiable and gives you a ReorderDifference<Item.ID, ReorderableSingleCollectionIdentifier>:²

nonisolated func reorderContainer<Item>(
    for item: Item.Type,
    isEnabled: Bool = true,
    move: @escaping (ReorderDifference<Item.ID, ReorderableSingleCollectionIdentifier>) -> ()
) -> some View where Item : Identifiable, Item.ID : Sendable

Two design decisions matter here. First, the framework drives the interaction: as Apple’s documentation describes it, a reorderable item can be lifted with a drag gesture, a placeholder view takes its position to show where the item will land, and the placeholder tracks the drag through the container.² You no longer build that affordance; you describe the collection and react to the result. Second, isEnabled is a parameter rather than a separate modifier, so an edit-mode toggle becomes one boolean instead of conditional view construction.

When a container holds more than one collection, you reach for the overload that takes a collection identifier type, reorderContainer(for:in:isEnabled:move:):²⁷

nonisolated func reorderContainer<Item, CollectionID>(
    for item: Item.Type,
    in collectionID: CollectionID.Type,
    isEnabled: Bool = true,
    move: @escaping (ReorderDifference<Item.ID, CollectionID>) -> ()
) -> some View where Item : Identifiable, CollectionID : Hashable, CollectionID : Sendable, Item.ID : Sendable

The ReorderDifference is now keyed by both the item ID and a collection ID, so a move that crosses from one section into another is expressible. Apple’s guidance is direct: use the multi-collection overload when your container has several collections, and the single-collection convenience when it has one.²⁷ The reorderable() modifier accepts the matching collection identifier when you need to disambiguate.³

Apple enables reordering by adding reorderable() to a ForEach and a reorderContainer to its parent, handling the difference in the closure.

In session 271, Apple shows the same reorder code carrying unchanged from a List to a LazyVGrid, because the modifiers describe the collection rather than the container, so reordering works in any container that supports drag and drop.³⁶

Lazy Drag Containers

The other half of the iOS 27 drag story is about cost. Classic draggable requires you to produce the payload up front, which means the framework may need to materialize an item (and sometimes render it) before a drag even begins. For a lazy list of thousands of rows, that is wasted work.

dragContainer(for:itemID:in:_:) defines a container of draggable views and asks for the payload only once, as a closure over the dragged identifiers:⁴

nonisolated func dragContainer<ItemID, Item, Data>(
    for itemType: Item.Type = Item.self,
    itemID: KeyPath<Item, ItemID>,
    in namespace: Namespace.ID? = nil,
    _ payload: @escaping (Array<ItemID>) -> Data
) -> some View where ItemID : Hashable, ItemID : Sendable, Item : Transferable, Item == Data.Element, Data : Collection

Inside that container, each draggable child uses draggable(containerItemID:containerNamespace:), which carries only the item’s identifier:⁵

nonisolated func draggable<ItemID>(
    containerItemID: ItemID,
    containerNamespace: Namespace.ID? = nil
) -> some View where ItemID : Hashable, ItemID : Sendable

The reason this is the better default for large collections is in Apple’s own description: because the modifier supplies only an identifier and not the payload, it works lazily, so the framework asks for the actual dragged items only when the drag starts and does not have to render a view in order to access its payload.⁵ A Fruit value that identifies itself by name (and never conforms to Identifiable) can still be the source of a multi-item drag, because the container keys off the KeyPath you provide rather than an Identifiable conformance.⁴

Worth flagging for cross-platform code: dragContainer and draggable(containerItemID:containerNamespace:) are available on macOS 26.0, where most of the rest of this release is macOS 27.0, so the lazy-drag API is one you could have already adopted on the Mac.⁴⁵

A New Document Model

DocumentGroup and FileDocument carried SwiftUI’s document apps for years, but the read and write sides were entangled in a single conformance. iOS 27 splits them. Reading and writing are now separate protocols, the on-disk logic is its own layer, and a read-write type composes both.

The two top-level protocols are ReadableDocument and WritableDocument:⁶⁷

protocol ReadableDocument : AnyObject
protocol WritableDocument : AnyObject

A read-only type conforms to ReadableDocument alone. A read-write type conforms to both, and Apple provides a Document typealias that bundles the two so you can adopt the pair without naming each one.⁶⁷ Both are class-bound (: AnyObject), which is the visible signal that documents are reference types in this model.

The actual disk I/O moves into a reader and a writer abstraction, DocumentReader and DocumentWriter, each parameterized by the snapshot type your document serializes:⁸⁹

protocol DocumentReader<Snapshot>
protocol DocumentWriter<Snapshot>

Most apps never implement those by hand. For documents of small and medium size that need no custom logic, SwiftUI ships FileWrapperDocumentReader and FileWrapperDocumentWriter, each backed by a file wrapper and described by Apple as the efficient choice for the simple case:¹⁰¹¹

struct FileWrapperDocumentReader<Snapshot>
struct FileWrapperDocumentWriter<Snapshot>

Tying the open document together is URLDocumentConfiguration, a main-actor class that holds the settings and properties of an open document:¹²

@MainActor final class URLDocumentConfiguration

Export flows through an updated fileExporter that takes a WritableDocument whose writer targets a URL:²⁸

nonisolated func fileExporter<D>(
    isPresented: Binding<Bool>,
    document: D?,
    contentType: UTType? = nil,
    defaultFilename: String? = nil,
    onCompletion: @escaping (Result<URL, any Error>) -> Void,
    onCancellation: (() -> Void)? = nil
) -> some View where D : WritableDocument, D.Writer.Destination == URL

The constraint D.Writer.Destination == URL is the load-bearing part: the exporter only accepts a writable document whose writer writes to a URL, which is exactly the file-on-disk case the system dialog handles. Apple documents the lifecycle precisely: the dialog appears only when document is non-nil, isPresented is set to false before onCompletion runs, and a user cancellation sets isPresented to false and calls onCancellation.²⁸ The split between readable and writable is what lets a viewer-only feature import a document without ever conforming to the write side.

Toolbars That Decide What Survives

Toolbars run out of room. A compact-width iPhone, a resized Mac window, or an active search field can all leave fewer slots than you have controls. Before iOS 27, the framework made the eviction decisions for you. Now you make them.

ToolbarOverflowMenu is the explicit overflow surface. Apple describes it as actions that are always placed in the toolbar’s overflow menu regardless of toolbar mode, platform, or customizability, and on iOS and visionOS that content lands in the overflow menu in the navigation bar:¹³

nonisolated struct ToolbarOverflowMenu<Content> where Content : View

For the controls that should resist overflow, the new topBarPinnedTrailing placement pins an item to the trailing edge of the toolbar:¹⁴

static let topBarPinnedTrailing: ToolbarItemPlacement

The nuance Apple documents is that pinned items only move to the overflow menu when search is active and there isn’t enough room, and on iOS and visionOS the top bar is the navigation bar.¹⁴ So topBarPinnedTrailing is for the one or two controls you never want buried unless search forces the issue.

When the choice is relative rather than absolute, visibilityPriority(_:) on ToolbarContent ranks items so the framework knows the eviction order:¹⁵

@MainActor @preconcurrency
func visibilityPriority(_ priority: ToolbarItemVisibilityPriority) -> some ToolbarContent

Apple’s rule: when toolbar space is limited, items with a lower priority move into the overflow menu before items with a higher priority.¹⁵ An important control can sit at the trailing edge yet still be shown as the window shrinks. Paired with topBarPinnedTrailing and ToolbarOverflowMenu, you now have a full vocabulary for graceful degradation: pin the essential, prioritize the rest, and route the always-secondary into overflow.

One related modifier ties the toolbar to scroll behavior and to the Liquid Glass chrome that iOS 26 introduced. toolbarMinimizeBehavior(_:for:) enables toolbar minimization in response to scrolling, and Apple notes that when the navigation bar minimizes, an integrated top tab bar minimizes with it:²⁹

nonisolated func toolbarMinimizeBehavior(
    _ behavior: ToolbarMinimizeBehavior,
    for bars: ToolbarPlacement...
) -> some View

The supported placement is the navigation bar, and by default the safe area adjusts as the bar minimizes.²⁹ If you adopted Liquid Glass toolbars and wanted them to recede as the user reads, this is the modifier that does it.

Item-Based Alerts And Error Presentation

SwiftUI’s alert API has long had a boolean form (alert(_:isPresented:)) that forces you to stash the alert’s data in a separate @State alongside the presentation flag. iOS 27 adds the item-based forms that the sheet and popover APIs already had, so the data is the trigger.

The item-based alert presents whenever the binding is non-nil and passes the unwrapped value into your actions builder:¹⁷

nonisolated func alert<A, T>(
    _ title: Text,
    item data: Binding<T?>,
    @ContentBuilder actions: (T) -> A
) -> some View where A : View

There is a matching overload that adds a message builder, alert(_:item:actions:message:), and an equivalent pair for confirmationDialog, so the same item-driven pattern carries across alerts and dialogs.¹⁸³⁰³¹ Apple’s contract is the same in each: the data must be non-nil for the presentation to appear, and changes you make to the data after the presentation occurs are ignored.¹⁸

The error-presentation overloads are the genuinely new capability. Instead of mapping an error into a custom struct, you bind an Error directly:¹⁶

nonisolated func alert<E, A, M>(
    error: Binding<E?>,
    @ContentBuilder actions: (E) -> A,
    @ContentBuilder message: (E) -> M
) -> some View where E : Error, A : View, M : View

The behavior is what makes it worth adopting. When the error value isn’t nil, the system presents the alert, and the title is inferred from the error’s errorDescription if the error is a LocalizedError; otherwise the title falls back to the localized description.¹⁶ A LocalizedError you already defined now drives its own alert title with no extra wiring. A simpler overload, alert(error:actions:), drops the message builder when an OK action is all you need:¹⁹

nonisolated func alert<E, A>(
    error: Binding<E?>,
    @ContentBuilder actions: () -> A
) -> some View where E : Error, A : View

struct EditorView: View {
    @State private var saveError: SaveError?

    var body: some View {
        Form { /* ... */ }
            .alert(error: $saveError) { error in
                Button("Retry") { retry() }
                Button("Cancel", role: .cancel) { }
            } message: { error in
                Text(error.recoverySuggestion ?? "")
            }
    }
}

The pattern that disappears: a hand-rolled AlertError struct, an identifiable wrapper, and the mapping code between your real error type and the alert’s data source. You bind the Error? your code already produces.

AsyncImage Grows Up With URLRequest

AsyncImage shipped with a URL initializer and no way to set headers, a cache policy, or a timeout. The iOS 27 additions take a URLRequest, which is the object that carries all three.

The simplest form loads and displays an image from a request:²⁰

nonisolated init(request: URLRequest, scale: CGFloat = 1) where Content == Image

The phased form gives you the AsyncImagePhase to drive a content closure, and Apple notes you can specify the cache policy and timeout interval via the request:³²

nonisolated init(
    request: URLRequest?,
    scale: CGFloat = 1,
    transaction: Transaction = Transaction(),
    @ContentBuilder content: @escaping (AsyncImagePhase) -> Content
)

There is also a content/placeholder form for the common “show this until it loads, show that on success” split.³³ The behavior across all three is the documented AsyncImage contract: SwiftUI shows a placeholder until the load completes, swaps in the image on success, and keeps the placeholder on failure.²⁰

The companion modifier is asyncImageURLSession(_:), which hands the AsyncImage instances inside a view a URLSession to fetch with:³⁴

nonisolated func asyncImageURLSession(_ urlSession: URLSession) -> some View

var body: some View {
    List(avatars) { avatar in
        AsyncImage(request: URLRequest(url: avatar.url))
            .frame(width: 44, height: 44)
    }
    .asyncImageURLSession(authenticatedSession)
}

The combination is the answer to authenticated image loading. A request lets you attach an Authorization header or a custom cache policy; the session modifier lets a whole subtree share one configured URLSession (custom headers, a disk cache, a proxy) instead of each AsyncImage falling back to the shared session. For an app loading avatars behind a token, that is the difference between working and not.

Also Landing

Several smaller additions are worth a line each, because each one removes a specific friction.

swipeActions gains an overload with an onPresentationChanged: closure that fires with true when a row’s swipe actions become visible and false when they dismiss, so you can dim a row or update surrounding chrome while actions show.²¹ For custom row layouts built on ScrollView or LazyVStack rather than List, swipeActionsContainer() coordinates dismissal and mutual exclusion across rows the way List already does automatically (applying it to a List is a no-op).²²

NavigationTransition.crossFade is a transition that cross-fades between the appearing and disappearing views; specified on a sheet, it fades the sheet in over the content instead of moving it up to cover the content.²³ TabRole.prominent gives one tab a prominent visual treatment in supported tab bars, and Apple notes that with no explicit .prominent tab, a .search role tab may receive the prominent treatment by default.²⁴

UIHostingSceneDelegate extends UISceneDelegate to bridge SwiftUI scenes, letting UIKit activate a SwiftUI scene declared in the conforming class’s static rootScene property.²⁵ (It is the one item here that traces back to iOS 26.0 on most platforms, reaching tvOS in the 27.0 beta.²⁵) And GestureInputKinds is an option set that specifies which input kinds a gesture should recognize, the foundation for gestures that distinguish, say, touch from pointer.²⁶

Adoption Priorities

A release this wide rewards triage. Reach for these first.

1. Replace hand-written reordering. If you maintain onMove index math, reorderContainer(for:isEnabled:move:) plus reorderable() is a net deletion of code and a better interaction (the placeholder affordance is the system’s, not yours).²³ For list-heavy apps, the reorder API carries the most weight in the release.
2. Adopt the error-binding alerts. alert(error:actions:message:) removes the custom error-wrapper struct from every screen that surfaces failures, and a LocalizedError you already have now titles its own alert.¹⁶ Low effort, immediate readability.
3. Switch large drag sources to lazy containers. Any list of more than a few hundred draggable rows benefits from dragContainer(for:itemID:in:_:) plus draggable(containerItemID:containerNamespace:), because the framework stops materializing payloads it may never use.⁴⁵
4. Give your toolbars a priority story. If your toolbar ever overflows on compact width, visibilityPriority(_:), topBarPinnedTrailing, and ToolbarOverflowMenu let you decide what survives instead of accepting the framework’s defaults.¹³¹⁴¹⁵
5. Migrate document apps deliberately, not reflexively. The ReadableDocument/WritableDocument split is the right model, but it is a larger change than the others; adopt it when you are already touching the document layer, and lean on FileWrapperDocumentReader/FileWrapperDocumentWriter for the small-and-medium case rather than implementing the reader and writer protocols by hand.⁶⁷¹⁰¹¹

The throughline: adopt the additions that delete code you maintain, defer the ones that restructure code that already works.

FAQ

How do I make a SwiftUI list reorderable in iOS 27?

Declare reorderContainer(for:isEnabled:move:) on the container and apply reorderable() to the DynamicViewContent (typically a ForEach) inside it. The container’s move closure receives a ReorderDifference you apply to your model; the framework handles the drag gesture, the lift, and the placeholder that marks the drop position.²³ Use the reorderContainer(for:in:isEnabled:move:) overload with a collection identifier type when one container holds multiple collections.²⁷

What is the difference between draggable(containerItemID:) and the old draggable?

draggable(containerItemID:containerNamespace:) carries only the item’s identifier, not the payload, so it works lazily inside a dragContainer(for:itemID:in:_:): the framework requests the actual dragged items only when the drag starts and does not have to render a view to read its payload.⁴⁵ That makes it the right choice for large or lazily loaded collections where producing every payload up front would be wasted work.

How does the new SwiftUI document model differ from FileDocument?

iOS 27 splits reading and writing into separate protocols, ReadableDocument and WritableDocument, with DocumentReader/DocumentWriter doing the on-disk work and a Document typealias for a type that is both readable and writable.⁶⁷ For small and medium documents that need no custom logic, FileWrapperDocumentReader and FileWrapperDocumentWriter provide the implementation; URLDocumentConfiguration describes an open document.¹⁰¹¹¹² The split lets a viewer-only feature conform to just the read side.

Can I show an alert directly from an Error in SwiftUI now?

Yes. alert(error:actions:message:) and alert(error:actions:) take a Binding<E?> where E : Error. When the bound error is non-nil the system presents the alert, and if the error conforms to LocalizedError, the title is inferred from its errorDescription; otherwise it uses the localized description.¹⁶¹⁹ You no longer wrap the error in a custom identifiable struct.

How do I control which toolbar items disappear when space is tight?

Use visibilityPriority(_:) on your ToolbarContent to rank items: lower-priority items move into the overflow menu before higher-priority ones as space shrinks.¹⁵ Use topBarPinnedTrailing to pin a control to the trailing edge so it only moves to overflow when search is active and there isn’t room, and ToolbarOverflowMenu to declare actions that always live in the overflow menu.¹³¹⁴

Can AsyncImage send custom headers or set a cache policy in iOS 27?

Yes. The AsyncImage(request:scale:) family takes a URLRequest, which carries headers, cache policy, and timeout interval; Apple notes you can specify the cache policy and timeout via the request.²⁰³² To share a configured URLSession (for authentication or a custom cache) across the AsyncImage instances in a subtree, apply asyncImageURLSession(_:).³⁴

The full Apple Ecosystem cluster: the SwiftUI substrate (result builders, opaque types, the value-typed view tree); the Liquid Glass patterns that the iOS 27 toolbar-minimize behavior plays into; the @Observable internals that drive the state layer under every view in this post; and the parallel App Intents in iOS 27 surface for background execution, sync, and Spotlight. The hub is at the Apple Ecosystem Series. For broader iOS-with-AI-agents context, see the iOS Agent Development guide.

References