# AsyncImage
**SDK Version:** 27.0 and later

`AsyncImage` loads an image from a URL and displays it as it arrives. In the 2027 OS releases it applies standard HTTP caching by default: responses are cached according to the server's cache headers, so an image that already loaded can be served from the cache instead of downloaded again, with no code change and no API to enable. Two new entry points add control on top of that default: an initializer that takes a `URLRequest` in place of a `URL` (to set the cache policy or any other request property per image), and the `asyncImageURLSession(_:)` modifier (to supply a `URLSession` with its own `URLCache`).

If the user's deployment target is below iOS 27 / macOS 27 / watchOS 27 / tvOS 27 / visionOS 27, the new `AsyncImage(request:)` initializers and the `asyncImageURLSession(_:)` modifier require availability gating. The default HTTP caching described in the next section is different: it is runtime behavior, not an API call, and applies whenever the app runs on a 2027 OS release regardless of the build SDK or deployment target. A generic "I want caching" ask on a deployment target below SDK 27 needs no code change; the existing `AsyncImage(url:)` already gets the cache on iOS 27+ devices.

## Default HTTP caching

HTTP caching applies to every `AsyncImage` automatically; no API call turns it on, and the cache honors the response's cache headers. Existing `AsyncImage(url:)` code keeps working and gains the cache without modification. The cache lives in the framework's image loader and is not gated on the app's build SDK, so an app gets it when running on the 2027 OS releases even if it was built against an earlier SDK; only the customization below requires the 27 SDK.

```swift
AsyncImage(url: imageURL)   // cached per the server's headers; no change required
```

**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27.

## Per-request control with URLRequest

The new `init(request:)` initializers take a `URLRequest` instead of a `URL`, so you set the request's `cachePolicy` (or any other property) yourself. The remaining labels match the `URL` initializers: `scale:` (default `1`), and either a `content:`/`placeholder:` pair or a `transaction:` plus a single `content:` closure that receives an `AsyncImagePhase`. The bare `AsyncImage(request:)` with no closures renders the loaded image directly, like `AsyncImage(url:)`.

```swift
AsyncImage(request: URLRequest(url: imageURL, cachePolicy: .returnCacheDataElseLoad)) { image in
    image.resizable().scaledToFit()
} placeholder: {
    ProgressView()
}
// URLRequest.CachePolicy: .returnCacheDataElseLoad, .returnCacheDataDontLoad,
// .reloadIgnoringLocalCacheData, .reloadRevalidatingCacheData, .useProtocolCachePolicy
```

**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27.

## Custom URLSession

`asyncImageURLSession(_:)` sets the `URLSession` that the `AsyncImage` views in its subtree use to load images. Configure that session's `URLCache` to set the memory and disk capacity the images are cached with.

```swift
struct GalleryView: View {
    private static let imageSession: URLSession = {
        let configuration = URLSessionConfiguration.default
        configuration.urlCache = URLCache(memoryCapacity: 64 * 1024 * 1024,
                                           diskCapacity: 256 * 1024 * 1024)
        return URLSession(configuration: configuration)
    }()

    var body: some View {
        ScrollView {
            LazyVStack {
                ForEach(photos) { photo in
                    AsyncImage(request: URLRequest(url: photo.url, cachePolicy: .returnCacheDataElseLoad))
                }
            }
        }
        .asyncImageURLSession(Self.imageSession)
    }
}
```

**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27.

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| Default HTTP caching | 27 | 27 | 27 | 27 | 27 |
| `AsyncImage(request:…)` initializers | 27 | 27 | 27 | 27 | 27 |
| `asyncImageURLSession(_:)` | 27 | 27 | 27 | 27 | 27 |

# ContentBuilder Unification
**SDK Version:** 27.0 and later

Many of SwiftUI's result builders (most notably `@ViewBuilder`) have been unified under `@ContentBuilder`. This changes the type-checking model: result builders no longer constrain their block contents to conform to `View`. As a result, you may encounter source incompatibilities in existing code. Here are the issues and how to fix them:

## Ambiguous ShapeStyle Modifiers in `overlay` or `background`
**Issue:**
Code that passes a `ShapeStyle` expression with modifiers like `.opacity()` or `.blendMode()` directly to the deprecated non-builder `overlay` or `background` may produce:

```
error: ambiguous use of 'opacity'
error: ambiguous use of 'blendMode'
```

For example, this code will fail to compile:
```swift
import SwiftUI

struct ContentView: View {
    var body: some View {
        Text("Hello")
            .overlay(Color.blue.opacity(0.70).blendMode(.overlay))
    }
}
```

**Fix:**
Use the trailing-closure variant of `overlay` or `background` instead of passing the expression as a direct argument.

```swift
import SwiftUI

struct ContentView: View {
    var body: some View {
        Rectangle()
            .overlay { Color.blue.opacity(0.3).blendMode(.overlay) }
    }
}
```

**Reason:**
The `overlay` and `background` modifiers each have two overloads: one accepting a `View` (marked as disfavored) and one accepting a `ShapeStyle`. Separately, modifiers like `.opacity()` and `.blendMode()` on `ShapeStyle` are also overloaded to return either a `ShapeStyle` or a `View`. Previously, `@ViewBuilder`'s `View` constraint forced the compiler to pick the `View`-returning variant of `.opacity()`, which then resolved `overlay` unambiguously to the `ShapeStyle` overload.

With `@ContentBuilder` removing the `View` constraint, the `ShapeStyle`-returning variant of `.opacity()` must now be disfavored to preserve the previous default behavior. However, this creates a new problem when combined with `overlay`: each possible resolution path has exactly one disfavored overload (either the `View`-accepting `overlay` or the `ShapeStyle`-returning `.opacity()`), making the overall expression ambiguous. Using the trailing-closure variant explicitly selects the builder-based overload of `overlay`, breaking the tie.

## Ambiguous Type References When Another Module Shadows SwiftUI Types
**Issue:**
If your project imports a module that declares a type with the same name as a SwiftUI type (for example, its own `Color` type with a `.red` property), you may see:

```
error: ambiguous use of 'red'
```

This can occur with any duplicated static member (e.g., `.green`, `.blue`, `.clear`), not just `.red`, or a type with the same name as a SwiftUI type. For example, if a framework declared a type called `Text` with overloads that match those found in SwiftUI's `Text`, this would now be ambiguous. The common theme is that these were previously only disambiguated by the `View` constraint on `@ViewBuilder`'s `buildBlock`.

For example, this code will fail to compile if `MyPackage` also declares a `Color` type with a `.clear` member:
```swift
// In MyPackage:
public struct Color {
    public static let clear = Color()
}

// In your app:
import SwiftUI
import MyPackage

struct ContentView: View {
    var body: some View {
        Color.clear
    }
}
```

**Fix:**
Fully qualify the type to disambiguate which module's type you intend to use, or rename the type / members in `MyPackage` to make them distinct from those in SwiftUI.

```swift
import SwiftUI
import MyPackage

struct ContentView: View {
    var body: some View {
        SwiftUI.Color.clear
    }
}
```

**Reason:**
Previously, `@ViewBuilder`'s `View` constraint helped the compiler disambiguate between identically-named types across modules, because it could rule out the non-`View`-conforming candidate. With `@ContentBuilder` removing that constraint, the compiler sees both candidates as equally valid and reports an ambiguity.

## `TupleContent` vs `TupleView` Type Mismatch
**Issue:**
Code that explicitly references `TupleView` as a nested generic type parameter may produce:

```
error: cannot convert value of type 'VStack<TupleContent<Text, Text>>' to expected argument type 'VStack<TupleView<(Text, Text)>>'
```

This appears when `TupleView` is nested inside another container's generic parameter:
```
error: cannot convert value of type 'Label<TupleContent<Text, Text?>, Image?>' to expected argument type 'Label<TupleView<(Text, Optional<Text>)>, Optional<Image>>'
```

For example, this code will fail to compile:
```swift
import SwiftUI

struct CardView<Content: View>: View {
    var content: Content
    var body: some View { content }
    init(@ContentBuilder content: () -> Content) {
        self.content = content()
    }
}

extension CardView where Content == VStack<TupleView<(Text, Text)>> {
    init(title: String, subtitle: String) {
        self = CardView {
            VStack {
                Text(title)
                Text(subtitle)
            }
        }
    }
}
```

**Fix:**
Avoid hard-coding `TupleContent` or `TupleView` in generic type parameters. If you must spell the concrete type, use `TupleContent` instead of `TupleView` to match the new builder return type. If your deployment target is lower than any Apple OS 27.0, you can explicitly construct a `TupleView` inside the builder instead. Prefer using `some View` or other opaque types where possible.

```swift
import SwiftUI

struct CardView<Content: View>: View {
    var content: Content
    var body: some View { content }
    init(@ContentBuilder content: () -> Content) {
        self.content = content()
    }
}

extension CardView where Content == VStack<TupleContent<Text, Text>> {
    init(title: String, subtitle: String) {
        self = CardView {
            VStack {
                Text(title)
                Text(subtitle)
            }
        }
    }
}
```

or if your deployment target is lower than any Apple OS 27.0, you can do the equivalent with `TupleView`:

```swift
import SwiftUI

struct CardView<Content: View>: View {
    var content: Content
    var body: some View { content }
    init(@ContentBuilder content: () -> Content) {
        self.content = content()
    }
}

extension CardView where Content == VStack<TupleView<(Text, Text)>> {
    init(title: String, subtitle: String) {
        self = CardView {
            VStack {
                TupleView((
                    Text(title),
                    Text(subtitle)
                ))
            }
        }
    }
}
```

**Reason:**
The unified `@ContentBuilder` produces `TupleContent` rather than `TupleView` as the concrete return type for multi-expression builder blocks. When `TupleView` appears as a nested generic parameter (e.g., `VStack<TupleView<...>>`), the contextual type cannot propagate deep enough to guide the inner builder, causing a type mismatch. Updating the constraint to use `TupleContent`, or explicitly constructing `TupleView` inside the builder, resolves the issue.

## Empty Builder Body with MapKit
**Issue:**
When both SwiftUI and MapKit are dependencies of the same file an empty result builder body (or a `#if` block with no `#else` branch) inside of a nested builder will produce:

```
error: return type of property 'body' requires that 'EmptyMapContent' conform to 'View'
```

Note that this can happen even in files where `MapKit` is not explicitly imported if the project does not have member import visibility turned on. For this reason, do not rule this issue out just because the file doesn't import `MapKit`.

For example, this code will fail to compile:

```swift
import SwiftUI
import MapKit

struct ContentView: View {
    var body: some View {
        Group { }
    }
}
```

**Fix:**
Explicitly use `EmptyContent` (or `EmptyView`) rather than leaving the block empty.

```swift
import SwiftUI
import MapKit

struct ContentView: View {
    var body: some View {
        Group {
            EmptyContent()
        }
    }
}
```

**Issue:**
This also commonly occurs with conditional compilation blocks, as you can end up with an empty block in your else branch, for example the following code runs into the same issue when `MY_CONDITION` is `FALSE` as the block becomes empty:

```swift
import SwiftUI
import MapKit

struct ContentView: View {
    var body: some View {
        Group {
            #if MY_CONDITION
            MyView()
            #endif
        }
    }
}
```

**Fix:**
Add an explicit else branch with an `EmptyContent` (or `EmptyView`).

```swift
import SwiftUI
import MapKit

struct ContentView: View {
    var body: some View {
        Group {
            #if MY_CONDITION
            MyView()
            #else
            EmptyContent()
            #endif
        }
    }
}
```

**Reason:**
Without the `View` constraint on the builder, an empty builder body becomes ambiguous when MapKit is also imported, because MapKit defines its own result builder that can produce `EmptyMapContent`. Providing an explicit `EmptyContent()` (or `EmptyView()`) resolves the ambiguity by giving the compiler a concrete `View`-conforming expression.

## Type-Check Timeout in Swift Charts with Deeply Branching Content (Back-Deployment Only)
**Issue:**
When your project's minimum deployment target is lower than any Apple OS 27.0, deeply branching `if`/`else if` or `switch` statements inside a `Chart` closure may produce:

```
error: the compiler is unable to type-check this expression in reasonable time
```

This only occurs when back-deploying — projects that target OS 27.0 or later are not affected. It typically manifests when the branching logic has many cases (roughly 10+).

For example, this code will fail to compile:
```swift
import SwiftUI
import Charts

struct DataPoint {
    var index: Int
    var rate: Double
    var signal: Double
    var noise: Double
    var errors: Double
    var throughput: Double
    var txRate: Double
    var rxRate: Double
    var txFrames: Double
    var rxFrames: Double
    var channel: Double
    var bandwidth: Double
    var defaultValue: Double
}

struct MetricChartView: View {
    var selectedMetric: String
    var dataPoints: [DataPoint]

    var body: some View {
        Chart(dataPoints, id: \.index) { dataPoint in
            if selectedMetric == "Rate" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.rate))
                    .foregroundStyle(.blue)
            } else if selectedMetric == "Signal" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.signal))
                    .foregroundStyle(.green)
            } else if selectedMetric == "Noise" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.noise))
                    .foregroundStyle(.red)
            } else if selectedMetric == "Errors" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.errors))
                    .foregroundStyle(.orange)
            } else if selectedMetric == "Throughput" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.throughput))
                    .foregroundStyle(.purple)
            } else if selectedMetric == "TX Rate" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.txRate))
                    .foregroundStyle(.cyan)
            } else if selectedMetric == "RX Rate" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.rxRate))
                    .foregroundStyle(.mint)
            } else if selectedMetric == "TX Frames" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.txFrames))
                    .foregroundStyle(.indigo)
            } else if selectedMetric == "RX Frames" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.rxFrames))
                    .foregroundStyle(.brown)
            } else if selectedMetric == "Channel" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.channel))
                    .foregroundStyle(.teal)
            } else if selectedMetric == "Bandwidth" {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.bandwidth))
                    .foregroundStyle(.pink)
            } else {
                LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.defaultValue))
                    .foregroundStyle(.gray)
            }
        }
    }
}
```

**Fix:**
Extract the branching logic into a separate function annotated with `@ChartContentBuilder`. This switches back to the existing model for typechecking back-deployed code.

```swift
import SwiftUI
import Charts

struct MetricChartView: View {
    var selectedMetric: String
    var dataPoints: [DataPoint]

    var body: some View {
        Chart(dataPoints, id: \.index) { dataPoint in
            marks(for: dataPoint)
        }
    }

    @ChartContentBuilder
    private func marks(for dataPoint: DataPoint) -> some ChartContent {
        if selectedMetric == "Rate" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.rate))
                .foregroundStyle(.blue)
        } else if selectedMetric == "Signal" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.signal))
                .foregroundStyle(.green)
        } else if selectedMetric == "Noise" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.noise))
                .foregroundStyle(.red)
        } else if selectedMetric == "Errors" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.errors))
                .foregroundStyle(.orange)
        } else if selectedMetric == "Throughput" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.throughput))
                .foregroundStyle(.purple)
        } else if selectedMetric == "TX Rate" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.txRate))
                .foregroundStyle(.cyan)
        } else if selectedMetric == "RX Rate" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.rxRate))
                .foregroundStyle(.mint)
        } else if selectedMetric == "TX Frames" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.txFrames))
                .foregroundStyle(.indigo)
        } else if selectedMetric == "RX Frames" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.rxFrames))
                .foregroundStyle(.brown)
        } else if selectedMetric == "Channel" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.channel))
                .foregroundStyle(.teal)
        } else if selectedMetric == "Bandwidth" {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.bandwidth))
                .foregroundStyle(.pink)
        } else {
            LineMark(x: .value("X", dataPoint.index), y: .value("Y", dataPoint.defaultValue))
                .foregroundStyle(.gray)
        }
    }
}
```

**Reason:**
To support back-deployment of `@ContentBuilder` in Charts, a compatibility overload of `buildEither` is needed that emits a Charts-specific `BuilderConditional` type. This additional overload degrades the compiler's type-checking performance for branching expressions inside chart builders. When many branches are present, the exponential growth in candidate overloads causes the compiler to exceed its expression complexity limit. This only affects back-deployed configurations (minimum deployment target < OS 27.0) because the compatibility overload is not needed when targeting OS 27.0 or later. Extracting the branching into a dedicated `@ChartContentBuilder` function isolates the type-checking, keeping each expression within the compiler's complexity budget. While typechecking performance is degraded in this particular instance, this tradeoff improves typechecking performance even for projects with lower minimum deployment targets for chart content outside of this case, and for *all* SwiftUI content which imports Charts.

# Confirmation Dialog and Alert Item Binding
**SDK Version:** 27.0 and later

If the user's deployment target is below iOS 27 / macOS 27 / watchOS 27 / tvOS 27 / visionOS 27, the new APIs in this reference (`confirmationDialog(_:item:…)` and `alert(_:item:…)` overloads) require availability gating. See "Deployment target below SDK 27" below for the gating shape to use.

`confirmationDialog` and `alert` gain overloads that take an `item: Binding<T?>` in place of an `isPresented: Binding<Bool>`. The dialog or alert presents while the binding holds a value, the unwrapped value is passed to the `actions` (and optional `message`) closures, and SwiftUI resets the binding to `nil` when it is dismissed. This is the presentation shape of `sheet(item:)` applied to dialogs and alerts; the earlier forms drove presentation from a separate `Bool` and read the data from a stored optional or a `presenting:` argument. `T` has no `Identifiable` requirement. When a dialog or alert acts on a specific value, such as the row a person tapped or the item pending deletion, prefer this `item:` overload over a separate `isPresented` Bool, a `presenting:` argument, or the older `Alert`-returning `alert(item:)`: one optional drives presentation and hands the value to the `actions`/`message` builders.

## Confirmation dialog from an item binding

`confirmationDialog(_:item:titleVisibility:actions:)` presents while `item` is non-nil and passes the unwrapped value to `actions`; the overload with a trailing `message:` closure receives the value as well. The title is a `LocalizedStringKey`, `Text`, or `StringProtocol`, and `titleVisibility` defaults to `.automatic`.

```swift
struct PhotoGrid: View {
    @State private var photoToDelete: Photo?

    var body: some View {
        PhotoList(deleteAction: { photoToDelete = $0 })
            .confirmationDialog("Delete photo?", item: $photoToDelete) { photo in
                Button("Delete \(photo.name)", role: .destructive) {
                    delete(photo)
                }
            } message: { photo in
                Text("\(photo.name) will be removed from all of your devices.")
            }
    }
}
```

**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27.

## Alert from an item binding

`alert(_:item:actions:)` presents while `item` is non-nil and passes the unwrapped value to `actions`; the overload with a trailing `message:` closure receives the value as well. Like `confirmationDialog(_:item:)`, it takes a title plus `actions` (and optional `message`) builders. For a per-item alert, this is the form to use; do not synthesize a `Binding<Bool>` and pair it with `presenting:`, and do not reach for the `Alert`-returning `alert(item:) { _ in Alert(...) }` overload.

```swift
struct FolderView: View {
    @State private var pendingRename: Folder?

    var body: some View {
        FolderList(renameAction: { pendingRename = $0 })
            .alert("Rename folder", item: $pendingRename) { folder in
                Button("Rename") { rename(folder) }
                Button("Cancel", role: .cancel) {}
            } message: { folder in
                Text("Choose a new name for \(folder.name).")
            }
    }
}
```

**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27.

## Deployment target below SDK 27

When the user's deployment target is below SDK 27 and the answer needs a per-item dialog or alert, gate the new `item:` overload behind `#available` and provide a fallback for older OS versions using the existing `isPresented:` (and `presenting:` where the unwrapped value is needed). The shape:

```swift
@State private var photoToDelete: Photo?
@State private var isConfirmingDelete = false

var body: some View {
    SomeContent()
        .modifier(DeleteConfirmation(item: $photoToDelete, isPresented: $isConfirmingDelete))
}

private struct DeleteConfirmation: ViewModifier {
    @Binding var item: Photo?
    @Binding var isPresented: Bool

    func body(content: Content) -> some View {
        if #available(iOS 27, *) {
            content.confirmationDialog("Delete photo?", item: $item) { photo in
                Button("Delete \(photo.name)", role: .destructive) { /* delete */ }
            } message: { photo in
                Text("\(photo.name) will be removed.")
            }
        } else {
            content.confirmationDialog(
                "Delete photo?",
                isPresented: $isPresented,
                presenting: item
            ) { photo in
                Button("Delete \(photo.name)", role: .destructive) { /* delete */ }
            } message: { photo in
                Text("\(photo.name) will be removed.")
            }
        }
    }
}
```

Use this shape (or `@available(iOS 27, *)` on an enclosing declaration) whenever the prompt names a deployment target below SDK 27. Don't emit unconditional calls to the new `item:` overloads; the typecheck will fail with `'<API>' is only available in iOS 27.0 or newer`.

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| `confirmationDialog(_:item:titleVisibility:actions:)` / `…actions:message:)` | 27 | 27 | 27 | 27 | 27 |
| `alert(_:item:actions:)` / `…actions:message:)` | 27 | 27 | 27 | 27 | 27 |

# Reorderable Containers
**SDK Version:** 27.0 and later

SwiftUI now supports drag-to-reorder in *any* container (`List`, `LazyVStack`, `LazyVGrid`, stacks, or a custom layout), not just `List`. Previously, drag-to-reorder was effectively `List`-only (via `onMove(perform:)`) or hand-rolled with a drag gesture. Two modifiers work together: `.reorderable()` goes on the `ForEach` (it is declared on `DynamicViewContent`), and `.reorderContainer(for:…)` goes on the enclosing container. When a drag ends, SwiftUI calls your `move` closure with a `ReorderDifference` describing the change, which you apply to your own data.

**Availability:** iOS 27, macOS 27, watchOS 27, visionOS 27. **tvOS: unavailable.**

If the user's deployment target is below iOS 27 / macOS 27 / watchOS 27 / visionOS 27, do not use these APIs unconditionally.

## Basic usage

```swift
struct StickerGrid: View {
    @State private var stickers: [Sticker] = []

    var body: some View {
        ScrollView {
            LazyVGrid(columns: columns) {
                ForEach(stickers) { sticker in
                    StickerView(sticker)
                }
                .reorderable()
            }
            .reorderContainer(for: Sticker.self) { difference in
                // Update `stickers` to reflect the move (see "Applying the difference").
            }
        }
    }
}
```

`Sticker` must be `Identifiable` for the `for:` overload (it keys on `\.id`). If your type is not `Identifiable`, or you want a different identifier, use the `itemID:` keypath overload: `reorderContainer(for: Sticker.self, itemID: \.code)` paired with the same `.reorderable()`.

## Applying the difference

Your `move` closure receives a `ReorderDifference<ItemID, CollectionID>`:

```swift
public struct ReorderDifference<ItemID, CollectionID> {
    public var sources: [ItemID]            // the items being moved
    public var destination: Destination

    public struct Destination {
        @frozen public enum Position {
            case before(ItemID)             // insert the sources before this item
            case end                        // append the sources to the end
        }
        public var position: Position
        public var collectionID: CollectionID
    }
}
```

`sources` is the items being moved; `destination.position` is where they go (`.before(id)` places them ahead of that item, `.end` appends). Apply this to your data however fits your model. As one example, using a `Set` for O(1) membership and a single in-place pass, factored into a reusable extension on `ReorderDifference`:

```swift
extension ReorderDifference where CollectionID == ReorderableSingleCollectionIdentifier {
    func apply<C>(to collection: inout C)
        where C: RangeReplaceableCollection,
              C.Element: Identifiable,
              C.Element.ID == ItemID
    {
        let moving = Set(sources)
        guard !moving.isEmpty else { return }

        // One in-place pass: drop the moved items and capture them in order.
        var moved: [C.Element] = []
        moved.reserveCapacity(moving.count)
        collection.removeAll { element in
            guard moving.contains(element.id) else { return false }
            moved.append(element)
            return true
        }

        switch destination.position {
        case .before(let id):
            let index = collection.firstIndex { $0.id == id } ?? collection.endIndex
            collection.insert(contentsOf: moved, at: index)
        case .end:
            collection.append(contentsOf: moved)
        }
    }
}
```

(That example's `CollectionID == ReorderableSingleCollectionIdentifier` constraint scopes it to single-collection containers; sectioned containers route by `destination.collectionID` instead. See below.)

## Sections and multiple collections

When a container has more than one collection (for example, `List` sections), tag each `ForEach` with `.reorderable(collectionID:)` and declare the collection identifier type on the container with `reorderContainer(for:in:)`:

```swift
struct Category: Identifiable {
    let id = UUID()
    var name: String
    var items: [Item]
}

// In your view's body:
List {
    ForEach(categories) { category in
        Section(category.name) {
            ForEach(category.items) { item in
                ItemView(item)
            }
            .reorderable(collectionID: category.id)
        }
    }
}
.reorderContainer(for: Item.self, in: Category.ID.self) { difference in
    // Apply the move. difference.destination.collectionID identifies the
    // destination section; remove the items from their old section and insert
    // them at difference.destination.position.
}
```

The type you pass to `in:` is your section model's `ID` (here `Category.ID`), not SwiftUI's `Section`. For a single-collection container, the `CollectionID` is `ReorderableSingleCollectionIdentifier` (an opaque empty identifier SwiftUI supplies for you).

## Drag-and-drop integration

`.reorderContainer(for:)` already acts as a drag container and a drop destination, so dragging to reorder works on its own. To customize it, declare your own `dragContainer(for:)` (to control selection, the dragged item representation, or to let items drag out to other views and apps) or `dropDestination(for:)` (to accept dropped items at the reorder position) on the same container. A standalone `.draggable` does not customize the reorder container; provide a `dragContainer` instead.

> **Availability:** these drag-and-drop modifiers are iOS 27 / visionOS 27, and macOS 26 to 27. `dragContainer` / `draggable(containerItemID:)` / `dropDestination` are macOS 26, but `DropSession.reorderDestination(for:)` requires macOS 27 (see the table below). tvOS and **watchOS are unavailable**, so a reorderable list works on watchOS (reordering is local to the container), but this drag-and-drop integration, which relies on system-wide drag and drop, does not.

**Customize the drag.** Declare your own `dragContainer(for:)` on the container to build the drag payload from an item identifier. `.reorderable()` already marks each child as draggable through the container, so the children themselves stay bare:

```swift
LazyVGrid(columns: columns) {
    ForEach(stickers) { sticker in
        StickerView(sticker)
    }
    .reorderable()
}
.reorderContainer(for: Sticker.self) { difference in /* apply the move to stickers */ }
.dragContainer(for: Sticker.self) { draggedID in
    stickers.first { $0.id == draggedID }.map { [$0] } ?? []
}
```

Return an empty collection from the `dragContainer` closure to disable the drag for a given item.

**Combining items: drop one onto another.** Put `.dropDestination(for:isEnabled:)` on each child. SwiftUI invokes the closure only when `isEnabled` is true, so a per-item predicate (`canCombine`, a state check, etc.) goes in `isEnabled:`, not inside the closure. The closure's signature is `(items: [T], session: DropSession) -> Void`. SwiftUI handles drop visualization itself: while a drag hovers an `isEnabled` child, the system signals that item as the drop target, and when the drag moves between children the system shows a reorder gap. You do not need to add hover state to your view. Do not use the `dropDestination(for:) { } isTargeted: { }` overload here; that overload reports hover state for custom visual feedback, it does not gate combining, and it is the wrong choice for drop-to-combine.

```swift
LazyVGrid(columns: columns) {
    ForEach(stickers) { sticker in
        StickerView(sticker)
            .dropDestination(for: Sticker.self, isEnabled: sticker.allowsCombining) { items, _ in
                // Void-returning: no `return true` / `return false` in this closure.
                guard let i = stickers.firstIndex(where: { $0.id == sticker.id }) else { return }
                let droppedIDs = Set(items.map(\.id))
                stickers[i].name = ([stickers[i].name] + items.map(\.name)).joined(separator: "+")
                stickers.removeAll { droppedIDs.contains($0.id) }
            }
    }
    .reorderable()
}
.reorderContainer(for: Sticker.self) { difference in difference.apply(to: &stickers) }
.dragContainer(for: Sticker.self) { draggedID in
    stickers.first { $0.id == draggedID }.map { [$0] } ?? []
}
```

**Accepting drops at the reorder position.** Put `.dropDestination(for:)` on the container and ask the session where the drop landed via `reorderDestination(for:)`, which returns a `ReorderDifference.Destination?` (`nil` means the person dropped without hovering a specific item; append to the end in that case). This overload is for placement, not combining; for combine, use the per-child form above.

```swift
.dropDestination(for: Sticker.self) { items, session in
    guard let destination = session.reorderDestination(for: Sticker.self) else {
        stickers.append(contentsOf: items)
        return
    }
    switch destination.position {
    case .before(let id):
        let index = stickers.firstIndex { $0.id == id } ?? stickers.endIndex
        stickers.insert(contentsOf: items, at: index)
    case .end:
        stickers.append(contentsOf: items)
    }
}
```

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| `reorderable()` / `reorderContainer(for:…)` | 27 | 27 | 27 | n/a | 27 |
| `dragContainer` / `draggable(containerItemID:)` | 27 | 26 | n/a | n/a | 27 |
| `DropSession` / `dropDestination(for:…session…)` | 26 | 26 | n/a | n/a | 26 |
| `DropSession.reorderDestination(for:)` | 27 | 27 | n/a | n/a | 27 |

# @State as Macro
**SDK Version:** 27.0 and later

`@State` has been migrated from a property wrapper to a macro. As a result, you may encounter source incompatibility issues in existing or new code. Here are the issues and how to fix them:

## Init Assignment Errors
**Issue:**
Projects that provide an initial value for a `@State` variable decleration and try to assign its value again in a initializer, before all stored properties are assigned, will encounter errors like:

```
error: Variable 'self.name' used before being initialized
```

For example, this code will fail to compile:
```swift
import SwiftUI

struct ContentView: View {
    var name: String
    @State private var counter: Int = 0

    init(name: String) {
        self.counter = 42
        self.name = name
    }

    var body: some View { Text("\(name): \(counter)") }
}
```

**Fix:**
 Drop the initial value expression at `@State` decleration, only assign it in the init. This ensures the value is correctly initialized.

**Reason:**
The `@State` macro synthesizes real backing storage properties. If your `init` assigns to `@State` properties before other stored properties are set, the compiler catches this as premature `self` usage.

**Warning:**
Assigning a new value to a `@State` property that has an initial value is an anti-pattern and won't produce the expected behavior.

For example, the `body` for the following code will see `0` as the value for `counter`
```swift
struct ContentView: View {
    @State private var counter: Int = 0

    init() {
        self.counter = 42
    }
}
```

## Redeclaration errors with composed property wrappers
**Issue:**
Projects that apply additional property wrappers to properties using `@State` might see errors like:

```
error: invalid redeclaration of synthesized property '_counter'
```

**Fix:**
Refactor the property wrapper composition: remove the redundant wrapper or restructure so backing storage names don't collide. If unsure, ask the user how they prefer to proceed.

**Reason:**
Both the composed property wrapper and the `@State` macro try to synthesize a backing storage property with the same name.

## Private memberwise init not synthesized
**Issue:**
Normally, if a type has only private members, and no explicit initializer, Swift synthesizes a private memberwise `init` that's only accessible in inits defined in extensions of the type. For views with `@State`, this synthesis doesn't occur. This causes an error at the call site when attempting to use the missing `init`:

```
struct Foo: View {
  // all members that would be in the synthesized init are private
  @State private var bar = 0
  private let baz: Int
}

extension Foo {
  init(_ bar: Int, baz: Int) {
    self.init(bar: bar, baz) // error
  }
}
```

**Fix:**
Explicitly define the memberwise initializer instead of relying on the compiler-synthesized one.

**Reason:**
The `@State` macro generates two `init` accessors targeting the same backing property (`__y`) – one on the original property and one on the synthesized `_y` peer – which, per SE-0400, makes the compiler skip memberwise `init` synthesis when multiple `init` accessors target the same stored property.

# Swipe Actions
**SDK Version:** 27.0 and later

The `swipeActions(edge:allowsFullSwipe:content:)` row modifier previously took effect only inside a `List`. The 2027 SDKs let it work in any scrollable container (a `ScrollView` containing a `LazyVStack`, `LazyVGrid`, or a stack) once that container is marked with the new `swipeActionsContainer()` modifier, which coordinates the swipe across the items in the container. A new overload of the row modifier adds an `onPresentationChanged` callback that reports when a row's actions are revealed or hidden.

If the user's deployment target is below iOS 27 / macOS 27 / watchOS 27 / visionOS 27, the new `swipeActionsContainer()` modifier and the `swipeActions(…onPresentationChanged:)` overload require availability gating. The original `swipeActions(edge:allowsFullSwipe:content:)` row modifier on a `List` row has been available since iOS 15 / macOS 12 / watchOS 8 / visionOS 1 and does not need gating.

## Swipe actions in a scrollable container

Put `swipeActionsContainer()` on the scrollable container and keep the existing `swipeActions(edge:allowsFullSwipe:content:)` on each row inside it. The row modifier is unchanged: `edge` defaults to `.trailing` (pass `.leading` for the leading edge), `allowsFullSwipe` defaults to `true`, and the content builder holds the buttons.

```swift
struct StickerListView: View {
    @State private var stickers: [Sticker] = []

    var body: some View {
        ScrollView {
            LazyVStack {
                ForEach(stickers) { sticker in
                    StickerRow(sticker)
                        .swipeActions {
                            Button(role: .destructive) {
                                stickers.removeAll { $0.id == sticker.id }
                            } label: {
                                Label("Delete", systemImage: "trash")
                            }
                        }
                }
            }
        }
        .swipeActionsContainer()
    }
}
```

Without `swipeActionsContainer()` on the container, `swipeActions` on a row outside a `List` has no effect. The modifier also applies to a `LazyVGrid` or a plain stack inside the `ScrollView`.

**Availability:** `swipeActionsContainer()` is iOS 27, macOS 27, watchOS 27, visionOS 27; tvOS unavailable. The `swipeActions(edge:allowsFullSwipe:content:)` row modifier is iOS 15, macOS 12, watchOS 8, visionOS 1; tvOS unavailable.

## Reacting when actions are shown or hidden

The `swipeActions(edge:allowsFullSwipe:content:onPresentationChanged:)` overload adds an `onPresentationChanged` closure that receives `true` when the row's actions become visible and `false` when they hide.

```swift
StickerRow(sticker)
    .swipeActions {
        Button(role: .destructive) {
            stickers.removeAll { $0.id == sticker.id }
        } label: {
            Label("Delete", systemImage: "trash")
        }
    } onPresentationChanged: { isPresented in
        revealedSticker = isPresented ? sticker.id : nil
    }
```

**Availability:** iOS 27, macOS 27, watchOS 27, visionOS 27; tvOS unavailable.

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| `swipeActions(edge:allowsFullSwipe:content:)` (row modifier) | 15 | 12 | 8 | n/a | 1 |
| `swipeActionsContainer()` | 27 | 27 | 27 | n/a | 27 |
| `swipeActions(…onPresentationChanged:)` | 27 | 27 | 27 | n/a | 27 |

# Toolbar
**SDK Version:** 27.0 and later

If the user's deployment target is below iOS 27 / macOS 27 / watchOS 27 / visionOS 27, the new APIs in this reference (`visibilityPriority(_:)`, `ToolbarOverflowMenu` and its `toolbarOverflowMenu` modifier, `.topBarPinnedTrailing`, `toolbarMinimizeBehavior(_:for:)`, `toolbarMinimizationSafeAreaAdjustment(_:for:)`, `contentMarginsRemoved(_:)`, `ToolbarPlacement.statusBar`, and `EmptyView` as toolbar content) require availability gating. The `ForEach` toolbar conformance back-deploys to iOS 16 / macOS 13 / watchOS 9 / tvOS 16 / visionOS 1 when built with the 2027 SDK and does not need gating. See "Deployment target below SDK 27" below for the gating shape to use.

When a toolbar has more items than fit the available width (a narrow window, a resized app, or iPhone), the system moves the overflow into a trailing overflow menu. The 2027 SDKs add modifiers to control what stays in the bar, what overflows, and what is pinned, to minimize a bar as the person scrolls, and to adjust toolbar content margins and status-bar visibility. `ForEach` and `EmptyView` also work inside a `toolbar` builder now.

## Visibility priority

`visibilityPriority(_:)` sets how readily a piece of `ToolbarContent` (a `ToolbarItem` or `ToolbarItemGroup`) overflows when space is tight: higher-priority content stays in the bar, lower-priority content moves to the overflow menu first. The priorities are `.automatic` (the default), `.low`, and `.high`, or you can derive one relative to another with `ToolbarItemVisibilityPriority(higherThan:)` or `(lowerThan:)`.

```swift
.toolbar {
    ToolbarItemGroup {
        UndoButton()
        RedoButton()
    }
    .visibilityPriority(.high)
}
```

**Availability:** iOS 27, macOS 26.1, watchOS 27, tvOS 27, visionOS 27. `.low` and `.high` are iOS and macOS only; the relative initializers are iOS 27 / macOS 27. On watchOS, tvOS, and visionOS only `.automatic` exists.

## Overflow menu

`ToolbarOverflowMenu` holds content that always lives in the overflow menu instead of the bar. Its body is a view builder, so the buttons go directly inside it. The `.toolbarOverflowMenu { }` modifier on `View` does the same outside a `toolbar` builder.

```swift
.toolbar {
    ToolbarOverflowMenu {
        ChoosePhotoButton()
        ExportAsImageButton()
        ClearAllStickersButton()
    }
}
```

**Availability:** iOS 27, visionOS 27.

## Pinned trailing item

A `ToolbarItem` placed with `.topBarPinnedTrailing` stays in the trailing position and never moves to the overflow menu, no matter how constrained the bar is.

```swift
.toolbar {
    ToolbarItem(placement: .topBarPinnedTrailing) {
        ShareButton()
    }
}
```

**Availability:** iOS 27, visionOS 27.

## Minimize on scroll

`toolbarMinimizeBehavior(_:for:)` minimizes a bar as the person scrolls. It takes one of `ToolbarMinimizeBehavior.automatic` (the system decides), `.onScrollDown`, `.onScrollUp`, or `.never`. The companion `toolbarMinimizationSafeAreaAdjustment(_:for:)` controls whether content's safe area shrinks to follow the bar as it minimizes, with `.automatic`, `.enabled`, or `.disabled`.

```swift
ScrollView {
    StickerListView()
}
.toolbarMinimizeBehavior(.onScrollDown, for: .navigationBar)  // or .automatic, .onScrollUp, .never
```

**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27. `.onScrollDown` / `.onScrollUp` / `.never` and `.enabled` / `.disabled` are iOS only; other platforms use `.automatic`.

## Toolbar content margins

`contentMarginsRemoved(_:)` removes the default margins around a piece of toolbar content, so it sits flush with the edge of the bar.

```swift
.toolbar {
    ToolbarItem(placement: .topBarTrailing) {
        AvatarView()
    }
    .contentMarginsRemoved()
}
```

**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27.

## Status bar visibility

The status bar is now a `ToolbarPlacement`, so you control its visibility with `toolbarVisibility(_:for:)`. On iOS this is the replacement for `statusBarHidden(_:)`.

```swift
.toolbarVisibility(.hidden, for: .statusBar)
```

**Availability:** iOS 27.

## Dynamic content

`ForEach` now conforms to `ToolbarContent`, so a `toolbar` builder can generate items from a collection just as a view body does. `EmptyView` conforms now as well, for an explicit empty branch. (Conditionals such as `if` and `#if`, and multiple items in one builder, already worked before 27.)

```swift
.toolbar {
    ForEach(quickActions) { action in
        ToolbarItem {
            Button(action.title) { action.perform() }
        }
    }
}
```

**Availability:** the `ForEach` conformance back-deploys (iOS 16, macOS 13, watchOS 9, tvOS 16, visionOS 1) when built with the 2027 SDK; the `EmptyView` conformance requires iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27.

## Deployment target below SDK 27

When the user's deployment target is below SDK 27 and the answer needs any of the new APIs above, gate the whole `.toolbar { … }` body in a single `if #available` block and provide a fallback for older OS versions. Conditionals already worked in toolbar builders before SDK 27, so this is the cleanest place to put the gate:

```swift
.toolbar {
    if #available(iOS 27, *) {
        // New SDK 27 APIs go here, for example:
        ToolbarItemGroup { /* … */ }
            .visibilityPriority(.high)
        ToolbarItem(placement: .topBarPinnedTrailing) { /* … */ }
        ToolbarOverflowMenu { /* … */ }
    } else {
        // Older fallback: plain ToolbarItem entries (or whatever older toolbar shape works for the app).
        ToolbarItem { /* … */ }
    }
}
```

Use this shape (or `@available(iOS 27, *)` on an enclosing declaration) whenever the prompt names a deployment target below SDK 27. Don't emit unconditional calls to the APIs above; the typecheck will fail with `'<API>' is only available in iOS 27.0 or newer`.

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| `visibilityPriority(_:)`, `.automatic` | 27 | 26.1 | 27 | 27 | 27 |
| `.low` / `.high` | 27 | 26.1 | n/a | n/a | n/a |
| `init(lowerThan:)` / `init(higherThan:)` | 27 | 27 | n/a | n/a | n/a |
| `ToolbarOverflowMenu` / `toolbarOverflowMenu` | 27 | n/a | n/a | n/a | 27 |
| `.topBarPinnedTrailing` | 27 | n/a | n/a | n/a | 27 |
| `toolbarMinimizeBehavior(_:for:)`, `.automatic` | 27 | 27 | 27 | 27 | 27 |
| `.onScrollDown` / `.onScrollUp` / `.never` | 27 | n/a | n/a | n/a | n/a |
| `toolbarMinimizationSafeAreaAdjustment(_:for:)`, `.automatic` | 27 | 27 | 27 | 27 | 27 |
| `.enabled` / `.disabled` (safe-area adjustment) | 27 | n/a | n/a | n/a | n/a |
| `contentMarginsRemoved(_:)` | 27 | 27 | 27 | 27 | 27 |
| `ToolbarPlacement.statusBar` | 27 | n/a | n/a | n/a | n/a |
| `ForEach` as toolbar content (back-deploys) | 16 | 13 | 9 | 16 | 1 |
| `EmptyView` as toolbar content | 27 | 27 | 27 | 27 | 27 |