# @Animatable macro

To make the properties of a custom `View` or `Shape` participate in SwiftUI animations, conform such a type to the `Animatable` protocol. Use the `@Animatable` macro to avoid writing out the protocol requirement `animatableData`:

```swift
@Animatable
struct CoolShape: Shape {
    var width: CGFloat
    var angle: Angle
    // ...
}
```

If the property cannot participate in `animatableData`, the `@Animatable` macro will emit an error suggesting marking the property with `@AnimatableIgnored` or conform it to either the `VectorArithmetic` or `Animatable` protocol:

```swift
@Animatable
struct CoolShape: Shape {
    var width: CGFloat
    var angle: Angle
    var isOpaque: Bool // ❌ Cannot automatically synthesize 'animatableData'.
                       // Mark this property with '@AnimatableIgnored'.
                       // Conform the type of this property to 'Animatable' or 'VectorArithmetic'.
}
```

If changes to this property need to be animated, conform its type to either `Animatable` or `VectorArithmetic` protocols. Otherwise, opt-out the property from `animatableData` using `@AnimatableIgnored` macro:

```swift
@Animatable
struct CoolShape: Shape {
    var width: CGFloat
    var angle: Angle
    @AnimatableIgnored var isOpaque: Bool // opt-out the Bool property from 'animatableData'
}
```

# When to implement `animatableData`

Reach for an explicit `animatableData` when the interpolated value needs custom logic that doesn't correspond 1:1 to a stored property, like normalization, clamping, or driving a derived value.

For deployment target >= 26.0, use `AnimatableValues`:

```swift
// A wave shape whose `phase` needs to stay in 0..<2π during animation so
// long-running animations don't accumulate unbounded values, and whose
// `amplitude` must be clamped to `maxAmplitude` on every tick.
struct WaveShape: Shape {
    var amplitude: CGFloat
    var phase: CGFloat
    var maxAmplitude: CGFloat

    var animatableData: AnimatableValues<CGFloat, CGFloat> {
        get { AnimatableValues(amplitude, phase) }
        set {
            amplitude = min(max(newValue.value.0, 0), maxAmplitude)
            phase = newValue.value.1.truncatingRemainder(dividingBy: 2 * .pi)
        }
    }

    // ...
}
```

For earlier deployment targets, use `AnimatablePair`:

```swift
struct WaveShape: Shape {
    var amplitude: CGFloat
    var phase: CGFloat
    var maxAmplitude: CGFloat

    var animatableData: AnimatablePair<CGFloat, CGFloat> {
        get { AnimatablePair(amplitude, phase) }
        set {
            amplitude = min(max(newValue.first, 0), maxAmplitude)
            phase = newValue.second.truncatingRemainder(dividingBy: 2 * .pi)
        }
    }

    // ...
}
```

# Data Flow

How data flows through a SwiftUI app determines which views invalidate and when. `@State` owns view-local state. `@Observable` model objects carry data that's shared across a subtree, with per-property tracking that scopes invalidation to the exact views that read what changed. `Binding` lets a child edit state owned by a parent. The sections below cover what shape of data to hand each view, when to use each ownership tool, how to set up models so views invalidate as narrowly as possible, and how to handle side effects and two-way edits.

## Passing data into views

A view's input shape determines its invalidation surface for value-type inputs. SwiftUI compares value types field by field; if any field changed, the view's body runs. A view declared with `let user: User` (a struct) invalidates whenever any property of `User` is replaced — even properties this view never reads. A view declared with `let name: String` invalidates only when the name changes.

Reference types behave differently. SwiftUI compares class instances by pointer identity, not field by field — a view that holds a class reference re-invalidates only when the parent hands it a different instance. For `@Observable` class models, the observation system layers on top of that: it tracks which properties each view reads during `body` and invalidates only the views that read the specific property that changed (see "Model objects with @Observable" below). So the narrow-inputs rule is critical for value-type inputs and largely doesn't apply to reference-type inputs.

### Pass views only the data they read

For value-type inputs, this applies to every view, not just subviews extracted from a larger parent. A top-level screen view that takes a whole struct model just to display one of its fields invalidates on every unrelated update to that struct. Take only the data the view actually uses.

```swift
// AVOID: Taking the whole `User` struct (a value type) when the view
// reads only one field. SwiftUI compares `User` field by field, so
// `AvatarBadge` invalidates on any `User` change — bio edit, follower
// count tick, preferences toggle — even though it only displays
// `avatarURL`.
struct User {
    var name: String
    var bio: String
    var avatarURL: URL
    var followerCount: Int
    // ... more fields
}

struct AvatarBadge: View {
    let user: User

    var body: some View {
        AsyncImage(url: user.avatarURL)
    }
}
```

```swift
// PREFER: Take only the field the view actually reads.
struct AvatarBadge: View {
    let avatarURL: URL

    var body: some View {
        AsyncImage(url: avatarURL)
    }
}
```

"Reads" includes "forwards to a subview." A view that takes `let avatarURL: URL` and passes it to `AvatarBadge(avatarURL: avatarURL)` is using `avatarURL` — even though it never appears in a `Text(...)` or modifier directly. Forwarding a field to a child is a use of that field. The rule targets fields a view *truly* never touches (an unread sibling field of a struct input), not fields the view consumes by constructing children that render them. A parent that takes five fields and forwards each to the right subview is correctly factored, not "holding data it doesn't read."

### Watch the cost of large value-type inputs

The field-by-field comparison SwiftUI does for value-type inputs isn't free: every input check walks every field. For small structs (a few primitives, a URL) the cost is negligible. For a struct decoded from a large JSON payload — nested arrays, dictionaries, dozens of fields — it adds up. Every body evaluation in the parent does a deep comparison over the entire payload to decide whether the child changed, and every subview that takes the payload as an input pays the same cost.

The "narrow inputs" rule above already mitigates this — a subview that takes `let title: String` does one string comparison, not a tree walk over a decoded response.

```swift
// AVOID: Passing a large value-type payload through the view tree.
// Every parent body evaluation deep-compares the entire struct against
// the previous value just to decide whether the row changed, and every
// subview that takes it as input pays the same cost.
struct Article {
    let id: UUID
    let title: String
    let author: String
    let body: String                  // can be 50KB+
    let comments: [Comment]           // can be hundreds
    let related: [RelatedArticle]
    let editorialNotes: [Note]
    // ... many more fields
}

struct ArticleRow: View {
    let article: Article

    var body: some View {
        Text(article.title)
    }
}
```

```swift
// PREFER: The full payload doesn't live on any view. It's owned by the
// model layer (decoded once into an `@Observable`, or broken into
// smaller per-view structs), and views see only the narrow values they
// render. Nothing in the view tree pays a deep-comparison cost over
// `body`, `comments`, or `related`.
struct ArticleRow: View {
    let title: String

    var body: some View {
        Text(title)
    }
}
```

#### Break the payload into per-view structs

When every field of a large struct really is consumed across the view tree, the answer is not "pass it whole anyway." Break the payload into discrete structs that each belong to a specific view, so each view's comparison surface is bounded by what that view actually displays. Don't make the app's entire value-type data model the input to every view in the hierarchy.

#### Or hold the payload in an @Observable model

If you don't want to split a large value type into smaller ones — typically because the type maps cleanly to a server payload and reshaping it would ripple through decoding — put it inside an `@Observable` model and pass the model instead. Reference comparison is cheap (pointer identity), and the observation system invalidates only views that read individually-tracked properties. But take care with compound stored properties on the model: a view that reads an entire `Array`, `Dictionary`, or `Set` establishes a dependency on the *whole collection*, so any element change invalidates that view. See "Per-property dependency granularity on @Observable models" below for the mitigation — cache derived values or extract a smaller `@Observable` model and hand each view that.

## View-local state with @State

- Always mark `@State` properties as `private`. If you encounter a `@State` variable that already has an access control specified, recommend changing it to `private`, but don't change it (to avoid breaking the build), unless you are instructed to do that.

## Model objects with @Observable

Use `@Observable` (not `ObservableObject`) for classes that provide data to views. The macro generates per-property observation tracking that scopes invalidation to the exact views that read the changed property — far cheaper than `ObservableObject`'s coarse `objectWillChange` broadcasts.

Mark `@Observable` classes with `@MainActor` unless the project has Main Actor default actor isolation (typically set via `SWIFT_DEFAULT_ACTOR_ISOLATION` in the build settings). Views read the model on the main actor during body evaluation; without `@MainActor` the model's properties are reachable from any thread, and writes from background tasks can race with view reads. Swift 6 strict concurrency flags this.

`@Observable` is not supported on `actor` types.

```swift
// AVOID: @Observable class without @MainActor. Properties are reachable
// from any thread, but views read them on the main actor — background
// writes can race with main-actor reads, and strict concurrency will
// flag the model.
@Observable
final class OrderModel {
    var status: DeliveryStatus = .placed
}
```

```swift
// PREFER: @MainActor on the @Observable class. Reads and writes are
// confined to the main actor, matching how views consume the model.
// Background work that produces a new value hops to the main actor
// (e.g. `await MainActor.run { model.status = .shipped }`).
@MainActor
@Observable
final class OrderModel {
    var status: DeliveryStatus = .placed
}
```

### Make @Observable property types Equatable

Prefer making the types of stored properties in `@Observable` model objects conform to `Equatable`. The `@Observable` macro generates a setter that skips invalidation when the new value equals the current one — but only when it can compare them, which means only when the type is `Equatable`. Without that conformance, every set notifies, even when the new value is identical. This is an easy performance win for properties that are written frequently with the same value (e.g. from polling, streaming updates, or timers).

This applies to all OS releases that support `@Observable` (iOS 17 / macOS 14 and aligned) when built with current Xcode — the equality check is emitted into the generated setter as user code, not delegated to a runtime feature.

```swift
// AVOID: DeliveryStatus is not Equatable.
// Every assignment to `status` invalidates observing views, even if the
// value hasn't actually changed.
enum DeliveryStatus {
    case placed, preparing, shipped, delivered
}

@MainActor
@Observable
final class OrderModel {
    var status: DeliveryStatus = .placed
}
```

```swift
// PREFER: Making DeliveryStatus Equatable lets the @Observable setter
// short-circuit redundant invalidations when the same status is set
// again.
enum DeliveryStatus: Equatable {
    case placed, preparing, shipped, delivered
}

@MainActor
@Observable
final class OrderModel {
    var status: DeliveryStatus = .placed
}
```

The same principle applies to collection properties. When a property is an `Array` (or `Set`, `Dictionary`, etc.), the collection's `Equatable` conformance delegates to its elements. If the element type is not `Equatable`, the collection isn't either, so every assignment to the collection triggers invalidation even when the contents are identical.

```swift
// AVOID: Ingredient is not Equatable, so assigning the same array of
// ingredients to `recipe.ingredients` always invalidates observing views.
struct Ingredient {
    var name: String
    var quantity: Double
    var unit: String
}

@MainActor
@Observable
final class RecipeModel {
    var ingredients: [Ingredient] = []
}
```

```swift
// PREFER: Making Ingredient Equatable allows Array's built-in Equatable
// conformance to compare element-wise, so the @Observable setter skips
// redundant invalidations when the same ingredients are set again.
struct Ingredient: Equatable, Identifiable {
    var name: String
    var quantity: Double
    var unit: String
}

@MainActor
@Observable
final class RecipeModel {
    var ingredients: [Ingredient] = []
}
```

### Per-property dependency granularity on @Observable models

When a view reads a property of an `@Observable` model, the observation system records a dependency on that exact property and invalidates the view only when *that* property changes. So a view that reads `model.title` invalidates on `title` changes but not on `model.description` changes — this per-property tracking is the main reason `@Observable` is so much cheaper than `ObservableObject` for granular updates.

The subtlety is that "property" is the granularity, not "field within a property". A property whose type is itself compound — a struct, an `Array`, a `Dictionary`, a `Set` — creates a dependency on the *entire value*. Reading any field of a stored struct, or any element of a stored collection, establishes a dependency on the whole stored property. The subsections below cover the common shapes of this trap.

Computed properties still establish dependencies transitively: a computed `var selectedItem: Item? { items.first { $0.id == selectedID } }` reads `items` inside its body, so any view that reads `model.selectedItem` ends up with a dependency on `items`. Renaming the access doesn't change what observation tracks. The fix is to cache the derived value as its own stored property and keep it in sync.

### Cache derived @Observable values; computed properties still establish dependencies transitively

```swift
// AVOID: A view that needs only one item, but reaches it through the
// whole collection. Every change to `users` — add, remove, edit any
// field of any user — invalidates `CurrentUserBadge`.
@MainActor
@Observable
final class AppState {
    var users: [User] = []
    var currentUserID: User.ID?
}

struct CurrentUserBadge: View {
    let state: AppState

    var body: some View {
        if let id = state.currentUserID,
           let user = state.users.first(where: { $0.id == id }) {
            Text(user.name)
        }
    }
}
```

```swift
// AVOID (attempted fix that doesn't work): Wrapping the lookup in a
// computed property *looks* like it narrows the dependency, but the
// computed body reads `users` — so `state.currentUser` establishes a
// dependency on the whole array transitively. Renaming the access
// doesn't change what observation tracks.
@MainActor
@Observable
final class AppState {
    var users: [User] = []
    var currentUserID: User.ID?

    var currentUser: User? {
        users.first { $0.id == currentUserID }
    }
}

struct CurrentUserBadge: View {
    let state: AppState

    var body: some View {
        if let user = state.currentUser {
            Text(user.name)
        }
    }
}
```

```swift
// PREFER: Cache the derived value as its own stored property and keep
// it up to date in didSet. Views read the prepared property and
// invalidate only when *it* changes — not on every change to `users`.
@MainActor
@Observable
final class AppState {
    var users: [User] = [] {
        didSet { recomputeCurrentUser() }
    }
    var currentUserID: User.ID? {
        didSet { recomputeCurrentUser() }
    }

    private(set) var currentUser: User?

    private func recomputeCurrentUser() {
        currentUser = users.first { $0.id == currentUserID }
    }
}

struct CurrentUserBadge: View {
    let state: AppState

    var body: some View {
        if let user = state.currentUser {
            Text(user.name)
        }
    }
}
```

### Extract a smaller @Observable when many views share data

When a piece of data is read by many independent views — or by views that should be invalidation-isolated from each other — pull it into its own `@Observable` model and hand each view that smaller model rather than the larger one. The view's dependency surface is then bounded by the smaller model, and the larger model can change without rippling through.

### Multiple individual @Observable property reads are fine

A view that reads several individual properties from one `@Observable` model is **not** over-subscribed and doesn't need to be split. Per-property tracking already scopes the view's invalidation to exactly those properties; carving the model into per-property subviews adds indirection without changing what re-runs when. The granularity traps in this file are about *single* reads that pull in too much — a struct-typed field that drags the whole struct, an array access that drags the whole collection, a computed property that proxies the same wide read. They are not about views that legitimately read several already-narrow properties.

### Pass @Observable collection elements directly to row views

When iterating a collection from an `@Observable` model, the list view that holds the `ForEach` legitimately depends on the collection — it needs to re-run when elements are inserted, removed, or reordered. The row view shouldn't reach back into the model to look up its element by index or key, though: doing so makes every row depend on the whole collection, so editing one user invalidates every row. Pass the element value directly into the row.

#### Single-field rows: pass the field

```swift
// AVOID: Row reaches back into the model by index. Every UserRow's
// body reads `state.users`, so any edit to any user invalidates every
// row — not just the one whose data changed.
struct UserList: View {
    let state: AppState

    var body: some View {
        ForEach(state.users.indices, id: \.self) { index in
            UserRow(state: state, index: index)
        }
    }
}

struct UserRow: View {
    let state: AppState
    let index: Int

    var body: some View {
        Text(state.users[index].name)
    }
}
```

```swift
// PREFER: Pass the row only the field it displays. `UserList` depends
// on `state.users` (correct — the list shape depends on it), but each
// `UserRow` takes just the name it renders. Editing one user's email
// doesn't re-run any row's body; editing one user's name re-runs only
// that row.
struct UserList: View {
    let state: AppState

    var body: some View {
        ForEach(state.users) { user in
            UserRow(name: user.name)
        }
    }
}

struct UserRow: View {
    let name: String

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

#### Multi-field rows: pass a persisted @Observable instance

An alternative pattern, useful when each row genuinely observes several fields of its element: model each element as its own `@Observable` and have the parent **persist** the instances. The list view still depends on the array of references (so it re-runs on inserts, removes, and reorders), but each row's dependencies are scoped to its own model — a row can observe multiple properties of its user without depending on the whole collection or the whole struct, and editing one field of one user invalidates only the row that displays that user.

The instances must be persisted. Vending a freshly-constructed `@Observable` on every read hands each row a new reference on every parent body evaluation; stored references compare unequal each time, every row's body re-runs, and nothing has actually changed.

```swift
// PREFER (multi-field rows): Per-element @Observable models that the
// parent stores and reuses. `UserRow` observes its specific user
// directly, so editing one field of one user invalidates only that
// row — and the row gets to read multiple fields without paying the
// whole-collection cost.
@MainActor
@Observable
final class User: Identifiable {
    let id: UUID
    var name: String
    var email: String
    var avatarURL: URL

    init(id: UUID = UUID(), name: String, email: String, avatarURL: URL) {
        self.id = id
        self.name = name
        self.email = email
        self.avatarURL = avatarURL
    }
}

@MainActor
@Observable
final class AppState {
    var users: [User] = []  // persisted; each User's identity is stable
    // ... mutations modify existing User instances in place
}

struct UserList: View {
    let state: AppState

    var body: some View {
        ForEach(state.users) { user in
            UserRow(user: user)
        }
    }
}

struct UserRow: View {
    let user: User

    var body: some View {
        HStack {
            AsyncImage(url: user.avatarURL)
                .frame(width: 32, height: 32)
                .clipShape(Circle())
            VStack(alignment: .leading) {
                Text(user.name).font(.headline)
                Text(user.email).font(.caption)
            }
        }
    }
}
```

### Expose struct fields as individual @Observable properties

When an `@Observable` model holds a value-type struct as a stored property, the observation system tracks reads at the *property* level — not at the struct's fields. A view that reads `session.user.name` depends on `session.user`. Mutating any field of `user` — or replacing it with a new `User` value — invalidates every view that touched it, even views that only displayed `name`.

The fix is to expose the struct's fields as individual properties on the `@Observable` model. The observation system tracks each field separately, and a view that reads only `userName` invalidates only when `userName` changes.

```swift
// AVOID: User struct held as a single property on the @Observable
// model. `ProfileBadge` reads `session.user.name`, `session.user.email`,
// `session.user.avatarURL` — every one of those reads establishes a
// dependency on `session.user`. Editing `preferences` (or any other
// field of `user`) also invalidates the view.
struct User {
    var name: String
    var email: String
    var avatarURL: URL
    var preferences: Preferences
}

@MainActor
@Observable
final class UserSession {
    var user: User

    init(user: User) { self.user = user }
}

struct ProfileBadge: View {
    let session: UserSession

    var body: some View {
        HStack {
            AsyncImage(url: session.user.avatarURL)
                .frame(width: 32, height: 32)
                .clipShape(Circle())
            VStack(alignment: .leading) {
                Text(session.user.name).font(.headline)
                Text(session.user.email).font(.caption)
            }
        }
    }
}
```

```swift
// PREFER: Flatten the struct's fields onto the model. Each field is
// tracked independently. `ProfileBadge` depends on `userName`,
// `userEmail`, and `avatarURL` — not on `preferences` — so editing
// preferences no longer invalidates it.
@MainActor
@Observable
final class UserSession {
    var userName: String
    var userEmail: String
    var avatarURL: URL
    var preferences: Preferences

    init(user: User) {
        self.userName = user.name
        self.userEmail = user.email
        self.avatarURL = user.avatarURL
        self.preferences = user.preferences
    }
}

struct ProfileBadge: View {
    let session: UserSession

    var body: some View {
        HStack {
            AsyncImage(url: session.avatarURL)
                .frame(width: 32, height: 32)
                .clipShape(Circle())
            VStack(alignment: .leading) {
                Text(session.userName).font(.headline)
                Text(session.userEmail).font(.caption)
            }
        }
    }
}
```

If the struct needs to be round-tripped (re-encoded into a payload, sent back to a server) and you don't want to lose its shape, keep both: a `var user: User` for round-tripping and individual properties for view consumption, kept in sync via `didSet` on `user`.

## Side effects in views

### Isolating onChange(of:) side-effect invalidation

When a view uses `.onChange(of:)` to react to a dependency (an `@Environment` value, a `@Binding`, or a property from an `@Observable` object), that dependency is read in the view's body scope. This creates a dependency on that value: the view's body is re-evaluated every time the dependency changes, even if the dependency is not used for rendering.

If the view's body is expensive (deep hierarchy, many children), this causes unnecessary work. Extract the `.onChange` and the dependency it observes into a separate view dedicated to handling that side effect. This way only the lightweight side-effect view is re-evaluated when the value changes.

```swift
// AVOID: ContentView reads `counter` from the environment solely for
// .onChange. Every change to `counter` creates a dependency and
// re-evaluates the expensive ScrollView hierarchy.
struct ContentView: View {
    @State private var model = Model()
    @Environment(\.counter) private var counter

    var body: some View {
        ScrollView {
            // ... expensive view hierarchy ...
        }
        .onChange(of: counter) {
            model.counter = counter
        }
    }
}
```

```swift
// PREFER: Extract the dependency and .onChange into a ViewModifier.
// The modifier owns the read of `counter` — when counter changes, only
// the modifier's body re-runs, not ContentView's. The host view's
// dependency surface doesn't include `counter` at all.
struct CounterSyncModifier: ViewModifier {
    let model: Model
    @Environment(\.counter) private var counter

    func body(content: Content) -> some View {
        content
            .onChange(of: counter) {
                model.counter = counter
            }
    }
}

extension View {
    func counterSync(model: Model) -> some View {
        modifier(CounterSyncModifier(model: model))
    }
}

struct ContentView: View {
    @State private var model = Model()

    var body: some View {
        ScrollView {
            // ... expensive view hierarchy ...
        }
        .counterSync(model: model)
    }
}
```

The same principle applies to any dependency type - `@Binding`, `@Observable` properties, or combinations:

```swift
// AVOID: EditorView reads both `document.wordCount` and `isActive`
// solely for side effects. Changes to either re-evaluate the
// expensive editor body.
struct EditorView: View {
    var document: DocumentModel
    @Binding var isActive: Bool
    @State private var model = EditorModel()

    var body: some View {
        ScrollView {
            // ... expensive text editor hierarchy ...
        }
        .onChange(of: document.wordCount) {
            model.updateStatistics(wordCount: document.wordCount)
        }
        .onChange(of: isActive) {
            model.setActive(isActive)
        }
    }
}
```

```swift
// PREFER: Extract both side effects into a single ViewModifier.
struct EditorChangesModifier: ViewModifier {
    var document: DocumentModel
    @Binding var isActive: Bool
    let model: EditorModel

    func body(content: Content) -> some View {
        content
            .onChange(of: document.wordCount) {
                model.updateStatistics(wordCount: document.wordCount)
            }
            .onChange(of: isActive) {
                model.setActive(isActive)
            }
    }
}

extension View {
    func editorChanges(
        document: DocumentModel,
        isActive: Binding<Bool>,
        model: EditorModel
    ) -> some View {
        modifier(
            EditorChangesModifier(
                document: document,
                isActive: isActive,
                model: model
            )
        )
    }
}

struct EditorView: View {
    var document: DocumentModel
    @Binding var isActive: Bool
    @State private var model = EditorModel()

    var body: some View {
        ScrollView {
            // ... expensive text editor hierarchy ...
        }
        .editorChanges(document: document, isActive: $isActive, model: model)
    }
}
```

Apply this pattern when all of these hold:
- A dependency is read only for a side effect (`.onChange`), not for rendering.
- The parent view has a non-trivial body that would be expensive to re-evaluate.

Do NOT apply this pattern when:
- The dependency is also used directly in the view's rendering output. The view will invalidate regardless, so isolation provides no benefit.
- The view body is already trivial. The overhead of an extra view is not justified.

## Bindings

### Use KeyPath bindings, not closure bindings

Always prefer to use a KeyPath-based Binding with subscripts instead of a get-set binding with a closure. Consider this model and child view:

```swift
@Observable
final class ScoreboardModel {
    private(set) var scores: [String: Int] = [
        "Alice": 42, "Bob": 17, "Carol": 99,
    ]

    let players = ["Alice", "Bob", "Carol"]

    // A subscript with a labeled argument can be used as a functional
    // 'projection' into the underlying model if given a Binding to it.
    subscript(scoreFor player: String) -> Int {
        get { scores[player, default: 0] }
        set { scores[player] = newValue }
    }
}

/// Basic view with two-way binding to a score.
struct PlayerScoreRow: View {
    var player: String
    @Binding var score: Int

    var body: some View {
        HStack {
            Text(player)
                .frame(width: 80, alignment: .leading)
            Stepper("\(score) pts", value: $score, in: 0...999)
        }
    }
}
```

Don't use a closure to produce the binding for `PlayerScoreRow`. Instead use a binding that goes through the subscript. If there is no subscript existing, you may need to create one.

```swift
/// Parent view.
struct ScoreboardView: View {
    @State private var model = ScoreboardModel()

    var body: some View {
        NavigationStack {
            List(model.players, id: \.self) { player in
                // ❌ BAD: Creating a closure means a new heap allocation each
                // time `body` is run and can result in issues with comparison,
                // triggering unnecessary invalidations.
                let badModelBinding = Binding(
                    get: { model[scoreFor: player] }
                    set: { model[scoreFor: player] = newValue }
                )
                PlayerScoreRow(player: player, score: badModelBinding)

                // ✅ GOOD: A subscript with a labeled argument can be used as a
                // functional 'projection' into the underlying model if given a
                // Binding to it.
                @Bindable var model = model
                PlayerScoreRow(player: player, score: $model[scoreFor: player])
            }
            .navigationTitle("Scoreboard")
        }
    }
}
```

You don't need to use a subscript for no-argument projections.

```swift
@Observable
final class PlayerModel {
  /// 0 means paused; any positive value is the playback speed.
  var rate: Double = 0
}

// ❌ BAD: A subscript with a marker enum dresses up an argument-less projection.
// There are no arguments for the projection to depend on, so this is just a
// computed property with extra ceremony.

/// Marker selecting the play/pause projection on `PlayerModel`.
private enum PlaybackProjection {
  case isPlaying
}

extension PlayerModel {
  /// Projects whether playback is active. Setting it to `false` pauses by
  /// zeroing the rate, and `true` resumes at normal speed.
  fileprivate subscript(playback _: PlaybackProjection) -> Bool {
    get { rate > 0 }
    set { rate = newValue ? 1 : 0 }
  }
}

@Bindable var model = model
Toggle("Play", isOn: $model[playback: .isPlaying])

// ✅ GOOD: Just use a boolean property, no need for a subscript.

extension PlayerModel {
  /// Projects whether playback is active. Setting it to `false` pauses by
  /// zeroing the rate, and `true` resumes at normal speed.
  fileprivate var isPlaying: Bool {
    get { rate > 0 }
    set { rate = newValue ? 1 : 0 }
  }
}

@Bindable var model = model
Toggle("Play", isOn: $model.isPlaying)
```

# `@Entry` macro

When defining custom environment, transaction, container, or focused values, always prefer to use `@Entry` to reduce boilerplate code and avoid mistakes.

`@Entry` requires a stable default — one whose expression returns the same result on every read. See `environment.md` under "Unstable Environment Default Values" for the full rule, the unstable shapes to avoid (`Model()`, `Date()`, `UUID()`, fresh allocations, captured runtime values), and the three fix shapes (Option A: `static let` backing; Option B: manual `EnvironmentKey` with `static let defaultValue`; Option C: optional with `nil` default). The same rule applies to `@Entry` on `Transaction`, `ContainerValues`, and `FocusedValues`. Stable default shapes that don't need any of those fixes include literals (`"home"`, `0`, `true`), enum cases with no associated values (`.standard`), `nil` for an optional, and references to a stable instance (a `static let`, a module-level `let`, or a struct that captures one). When reviewing or writing an `@Entry` declaration, check the default expression against this rule before doing anything else.

Create custom environment, transaction and container values by extending the relevant structures with new properties and attaching the `@Entry` macro to the variable declarations:

```swift
extension EnvironmentValues {
    @Entry var myCustomValue: String = "Default value"
    @Entry var anotherCustomValue = true
}

extension Transaction {
    @Entry var myCustomValue: String = "Default value"
}

extension ContainerValues {
    @Entry var myCustomValue: String = "Default value"
}
```

Since the default value for `FocusedValues` is always nil, `FocusedValue`s entries cannot specify a different default value and must have an Optional type:

```swift
extension FocusedValues {
    @Entry var myCustomValue: String?
}
```

When reviewing existing code that defines custom environment, transaction, container, or focused values via manual `EnvironmentKey` / `ContainerValuesKey` / `FocusedValueKey` conformances and a `get`/`set` extension property, surface the `@Entry` refactor as a top-line review finding — not a footnote, not an "Optional Improvements" aside, not a "looks good, also consider…" tail. The manual form is older boilerplate `@Entry` was specifically designed to replace; treating the two as a stylistic toss-up is incorrect. The deployment target gates availability (`@Entry` requires iOS 18 / macOS 15 / Xcode 16); when the target isn't specified in the code under review, recommend the refactor without a defensive hedge — note availability as a one-line caveat at most. (Don't perform the rewrite unprompted during a review — show the diff or refactored snippet as the finding.)

# Environment Performance

## How environment comparison works

When an environment value propagates, SwiftUI compares the old and new value to decide whether each reader needs to re-evaluate. Four facts about that comparison drive the rest of this document:

- **Structs compare field-by-field.** A non-`Equatable` struct whose fields all look equal compares as equal — `Equatable` is a fast path, not a prerequisite.
- **Class references compare by identity.** Two references to the same instance are equal; reassigning to a freshly-allocated instance is not.
- **Function values (closures) can't be compared reliably.** SwiftUI treats each re-read as changed, and every reader in the subtree invalidates.
- **Every environment write propagates to the whole subtree.** When any key changes, readers re-read their keys. A reader that falls back to its *default* gets that default re-evaluated on every pass — so an unstable default invalidates on every unrelated env write.

The same model covers `EnvironmentValues` / `@Environment` and `FocusedValues` / `@FocusedValue`. Rules in the sections below apply to both.

## Closures in the Environment

This section is about **custom** environment and focus-value keys that you define. Framework-provided action types — `OpenURLAction`, `DismissAction`, `RefreshAction`, and similar — are designed to wrap a closure and pair with framework-provided keys (`\.openURL`, `\.dismiss`, `\.refresh`, etc.). Passing a closure to one of these is the intended API and is **not** the anti-pattern below. Do not propose defunctionalizing them, replacing them with a custom struct or protocol, or avoiding the matching framework key. Before flagging a closure-in-environment site, check whether the receiving key is framework-provided; if it is, skip this rule.

Never store closures or function values in your own custom environment keys. The same applies to `FocusedValueKey`. Closures can't be reliably compared, so views that read that environment key may invalidate, even if nothing has changed. The comparison heuristics are different depending on the level of compiler optimization, and vary for different signatures and captures. The rule is unconditional — even when a specific closure happens to compare equal right now (non-capturing no-ops often do), you have no control over future writer sites adding captures, and the framework gives you no way to guarantee otherwise. Don't attempt to engineer a way to make putting a closure in the environment or focus values work. Wrapping the closure as a stored property on a struct is also not an acceptable fix — the struct still contains a closure, so comparison still fails. The fix is to eliminate the closure entirely: store the data it would have captured as properties on a struct or model, and expose the behavior as a regular method or `callAsFunction`.

The shape of the fix depends on the construction of the closure at the call site.

The same FIX patterns apply to `FocusedValueKey`: substitute `FocusedValues` / `@FocusedValue` for `EnvironmentValues` / `@Environment` in any example below.

`@MainActor` on the `@Observable` classes in the examples below is the defensive default and is safe to keep. When the class is only read and mutated from view bodies (as is typical), the annotation can be omitted without losing correctness.

### Not a fix: Wrapping the closure in a struct

A struct that stores a closure as a property has the same problem as putting the closure directly in `@Entry` — the closure inside the struct still defeats comparison, and every body evaluation constructs a new struct with a freshly-allocated closure. SwiftUI treats the environment value as changed on every write, and every view that reads it invalidates.

```swift
// AVOID: A struct that stores a closure is not a real fix.
// The closure property still can't be compared, so FormFields
// invalidates on every body evaluation of FormContainer.

struct SubmitAction {
    var perform: (String) -> Void
}

extension EnvironmentValues {
    @Entry var submitAction = SubmitAction(perform: { _ in })
}

struct FormContainer: View {
    var body: some View {
        FormFields()
            .environment(\.submitAction,
                SubmitAction(perform: { print("Submit: \($0)") }))
    }
}
```

Use one of the FIX shapes below instead: store the data the closure would have captured as stored properties, and expose the behavior via a regular method or `callAsFunction` (with no closure property).

### Not a fix: Hoisting the closure to a stored property on the View

Lifting the closure to a `private let action: () -> Void = { ... }` on the `View` struct is not a fix either. SwiftUI re-instantiates `View` structs freely, so the `let` initializer re-runs and produces a fresh closure each time the struct is constructed; even when the pointer happens to be stable, closure comparison heuristics still treat them as unequal under some optimization levels. This is the same trap as wrapping in a struct — same conclusion, same fix.

### EXAMPLE: Closure with NO captures

```swift
// AVOID: Storing a closure in the environment.
// Closures can't be compared and all views that read this key will be invalidated even when the closure hasn't changed.

extension EnvironmentValues {
    @Entry var submitAction: (String) -> Void = { _ in }
}

struct FormContainer: View {
    var body: some View {
        FormFields()
            .environment(\.submitAction) { draft in
                print("Submit: \(draft)")
            }
    }
}

struct FormFields: View {
    // This view is always invalidated: SwiftUI cannot compare the closure
    // in submitAction, so it assumes the value changed every time.
    @Environment(\.submitAction) private var submit

    var body: some View {
        Button("Submit") { submit("hello") }
    }
}
```

### FIX: Closure with NO captures

**Option A: Defunctionalize into a struct with `callAsFunction`:**

```swift
// PREFER: A struct with callAsFunction keeps call-site ergonomics.
// SwiftUI can compare the struct's stored properties to skip redundant
// invalidation
struct SubmitAction {
    func callAsFunction(_ draft: String) {
        print("Submit: \(draft)")
    }
}

extension EnvironmentValues {
    @Entry var submitAction = SubmitAction()
}

struct FormContainer: View {
    var body: some View {
        FormFields()
            .environment(\.submitAction, SubmitAction())
    }
}

struct FormFields: View {
    @Environment(\.submitAction) private var submit

    var body: some View {
        // Reads like a closure call thanks to callAsFunction.
        Button("Submit") { submit("hello") }
    }
}
```

**Option B: Use an @Observable model:**

```swift
// PREFER: Use an @Observable model to hold the action.
// The model reference is compared by identity, so the environment value
// is stable and dependent views do not spuriously invalidate.
@MainActor
@Observable
final class FormHandler {
    func submit(_ draft: String) {
        print("Submit: \(draft)")
    }
}

struct FormContainer: View {
    @State private var handler = FormHandler()

    var body: some View {
        FormFields()
            .environment(handler)
    }
}

struct FormFields: View {
    @Environment(FormHandler.self) private var handler

    var body: some View {
        Button("Submit") { handler.submit("hello") }
    }
}
```

**Choosing between A and B:** Prefer Option A when the action is stateless and self-contained. Prefer Option B when the handler needs to coordinate with other state on a shared model, or when you want to reuse the same model for related functionality.

### EXAMPLE: Closure WITH captures

```swift
// AVOID: Storing a closure in the environment.
// Closures can't be compared and all views that read this key will be invalidated even when the closure hasn't changed.

extension EnvironmentValues {
    @Entry var submitAction: () -> Void = {}
}

struct FormContainer: View {
    @State private var draft = "hello"

    var body: some View {
        FormFields()
            .environment(\.submitAction) {
                print("Submit: \(draft)")
            }
    }
}

struct FormFields: View {
    // This view is always invalidated: SwiftUI cannot compare the closure
    // in submitAction, so it assumes the value changed every time.
    @Environment(\.submitAction) private var submit

    var body: some View {
        Button("Submit") { submit() }
    }
}
```

### FIX: Closure WITH Captures

**Option A: Defunctionalize into a struct with `callAsFunction`, and captures stored as properties on the struct:**

```swift
// PREFER: A struct with callAsFunction keeps call-site ergonomics.
// Store the previously captured @State as a property on the struct.

struct SubmitAction {
    var draft: String
    
    func callAsFunction() {
        print("Submit: \(draft)")
    }
}

extension EnvironmentValues {
    // `submitAction` is optional here because the action is invalid
    // without the draft value set. When fixing this issue optionality
    // should always be considered based on the context. This example
    // does not imply that the entry *must* be optional in all cases.
    @Entry var submitAction: SubmitAction?
}

struct FormContainer: View {
    @State private var draft = "hello"

    var body: some View {
        FormFields()
            .environment(\.submitAction, SubmitAction(draft: draft))
    }
}

struct FormFields: View {
    @Environment(\.submitAction) private var submit

    var body: some View {
        // Reads like a closure call thanks to callAsFunction.
        Button("Submit") { submit?() }
    }
}
```

**Option B: Use an @Observable model, with captures moved into the model as observable properties:**

```swift
// PREFER: Use an @Observable model to hold the action.
// Move the previously captured @State from the view into the model.

@MainActor
@Observable
final class FormHandler {
    var draft: String = "hello"

    func submit() {
        print("Submit: \(draft)")
    }
}

struct FormContainer: View {
    @State private var handler = FormHandler()

    var body: some View {
        FormFields()
            .environment(handler)
    }
}

struct FormFields: View {
    @Environment(FormHandler.self) private var handler

    var body: some View {
        Button("Submit") { handler.submit() }
    }
}
```

**Choosing between A and B:** Prefer Option A when the captured state is small, view-local, and not shared with other views. Prefer Option B when the state naturally belongs outside the view — multiple readers or writers, external mutation, or when you want `@Observable` per-property tracking across the subtree.

### EXAMPLE: Advanced Use Case With Generic Handler

In this case, the closure, `appearanceHandler`, is completely different depending on the view into which it's injected.

```swift
class MetricsTracker {
    func trackForm(name: String) { /* ... */ }
    func trackCart(itemCount: Int) { /* ... */ }
}

extension EnvironmentValues {
    @Entry var appearanceHandler: () -> Void = {}
}

struct MainView: View {
    @State private var tracker = MetricsTracker()
    @State private var formName = "Form1"
    @State private var cartItemCount = 0
    
    var body: some View {
        VStack {
            FormFields(name: formName)
                .environment(\.appearanceHandler) {
                    tracker.trackForm(name: formName)
                }
            ShoppingCart(itemCount: cartItemCount)
                .environment(\.appearanceHandler) {
                    tracker.trackCart(itemCount: cartItemCount)
                }
        }
    }
}

struct FormFields: View {
    // This view is always invalidated: SwiftUI cannot compare the closure
    // in appearanceHandler, so it assumes the value changed every time.
    @Environment(\.appearanceHandler) private var appearanceHandler
    
    let name: String
    
    var body: some View {
        Text(name)
        FormContent()
            .onAppear {
                appearanceHandler()
            }
    }
}

struct ShoppingCart: View {
    let itemCount: Int
    @Environment(\.appearanceHandler) private var appearanceHandler
    
    var body: some View {
        Text("Item Count: \(itemCount)")
        ItemList()
            .onAppear {
                appearanceHandler()
            }
    }
}
```

### FIX: Advanced Use Case With Generic Handler

**Option A: Defunctionalize into separate structs conforming to a shared protocol**
 
In cases where a closure is stored that could have an entirely different implementation depending on the context, generalize the closure into a handler that conforms to a 
protocol, and declare a conforming concrete implementation that encapsulates the captures.

The type of the @Entry should be the protocol, while the concrete types that conform to the protocol are injected into the environment for each view.

Within Option A, choose between `callAsFunction` and a named method based on call-site readability. Use `callAsFunction` when you're replacing an existing closure call site and want to preserve the `handler(x)` ergonomics. Use a named method (for example, `handleURL(_:)`, `onAppear()`, `submit(_:)`) when the protocol describes a specific, nameable operation — the call site `handler.handleURL(url)` reads better than `handler(url)` when the behavior isn't obvious from surrounding context.

```swift
class MetricsTracker {
    func trackForm(name: String) { /* ... */ }
    func trackCart(itemCount: Int) { /* ... */ }
}

protocol AppearanceHandler {
    func callAsFunction()
}

extension EnvironmentValues {
    @Entry var appearanceHandler: AppearanceHandler?
}

struct FormAppearanceHandler: AppearanceHandler {
    let tracker: MetricsTracker
    let name: String
    
    func callAsFunction() {
        tracker.trackForm(name: name)
    }
}

struct CartAppearanceHandler: AppearanceHandler {
    let tracker: MetricsTracker
    let itemCount: Int
    
    func callAsFunction() {
        tracker.trackCart(itemCount: itemCount)
    }
}

struct MainView: View {
    @State private var tracker = MetricsTracker()
    @State private var formName = "Form1"
    @State private var cartItemCount = 0
    
    var body: some View {
        VStack {
            FormFields(name: formName)
                .environment(\.appearanceHandler,
                    FormAppearanceHandler(tracker: tracker, name: formName))
            ShoppingCart(itemCount: cartItemCount)
                .environment(\.appearanceHandler,
                    CartAppearanceHandler(tracker: tracker, itemCount: cartItemCount))
        }
    }
}

struct FormFields: View {
    @Environment(\.appearanceHandler) private var appearanceHandler
    
    let name: String
    
    var body: some View {
        Text(name)
        FormContent()
            .onAppear {
                appearanceHandler?()
            }
    }
}

struct ShoppingCart: View {
    let itemCount: Int
    @Environment(\.appearanceHandler) private var appearanceHandler
    
    var body: some View {
        Text("Item Count: \(itemCount)")
        ItemList()
            .onAppear {
                appearanceHandler?()
            }
    }
}
```

**Option B: Unify related state and logic into a shared class**
 
In many cases, rethinking the way that data is modeled can eliminate the need for overly complex open ended closure-based implementations. Grouping together related properties into a unified source of truth can make it easier to avoid making things unnecessarily generic in a way that is more compatible with how SwiftUI performs view comparison.

```swift
class MetricsTracker {
    func trackForm(name: String) { /* ... */ }
    func trackCart(itemCount: Int) { /* ... */ }
}

@MainActor
@Observable
final class Model {
    private let tracker = MetricsTracker()
    
    var formName: String = "Form1"
    var cartItemCount: Int = 0
    
    func trackFormAppearance() {
        tracker.trackForm(name: formName)
    }
    
    func trackCartAppearance() {
        tracker.trackCart(itemCount: cartItemCount)
    }
}

struct MainView: View {
    @State private var model = Model()
    
    var body: some View {
        VStack {
            FormFields()
            ShoppingCart()
        }
        .environment(model)
    }
}

struct FormFields: View {
    @Environment(Model.self) private var model
    
    var body: some View {
        Text(model.formName)
        FormContent()
            .onAppear {
                model.trackFormAppearance()
            }
    }
}

struct ShoppingCart: View {
    @Environment(Model.self) private var model
    
    var body: some View {
        Text("Item Count: \(model.cartItemCount)")
        ItemList()
            .onAppear {
                model.trackCartAppearance()
            }
    }
}
```

**Choosing between A and B:** Prefer Option A (protocol + concrete handlers) when handler kinds are independent and the set is open — for example, if third parties may add new handlers. Prefer Option B (unified model) when the handlers share state (such as the common `tracker` here) and the set is closed; it avoids the existential and usually shrinks the code.

## Rapidly Updating Environment Values

Every update to an environment key incurs a cost for EVERY VIEW that reads ANY KEY, even ones that aren't being updated, from the environment in the affected subtree, as SwiftUI must check whether each view's value has changed. Avoid placing values that change at high frequency (scroll offset, window size, drag position) into the environment.

Common high-frequency sources to watch for when reviewing client code — if any of these flow into an `@Entry` value or `.environment(\.key, value)` modifier, treat it as this anti-pattern:

- Scroll offset from `scrollPosition` / `onScrollGeometryChange`
- Window or container size from `GeometryReader` / `onGeometryChange`
- Drag translation or current location from `DragGesture().onChanged`
- Per-frame animation progress (`TimelineView`, `CADisplayLink`-driven values)
- Timer-driven state (`.timer` publisher, `Timer`)
- Pointer / cursor / hover location

Instead, store frequently updated values in an `@Observable` model. `@Observable` tracks per-property access, so only views that read a specific property invalidate when it changes. Prefer coarsened boolean thresholds over point-precise values: a view that reads `isWide` only invalidates when crossing the boundary, not on every pixel of a resize.

```swift
// AVOID: Propagating a rapidly-changing CGFloat through the environment.
// Every pixel of a window resize incurs a comparison cost for all
// environment-reading views in the subtree.
extension EnvironmentValues {
    @Entry var windowWidth: CGFloat = 0
}

struct RootView: View {
    var body: some View {
        GeometryReader { proxy in
            ContentView()
                .environment(\.windowWidth, proxy.size.width)
        }
    }
}

struct ContentView: View {
    @Environment(\.windowWidth) private var width

    var body: some View {
        Text(width > 600 ? "Wide layout" : "Compact layout")
    }
}
```

```swift
// PREFER: Hold geometry in an @Observable model and expose coarsened
// thresholds. Views only invalidate when crossing a meaningful
// boundary, not on every pixel.
@MainActor
@Observable
final class ViewportModel {
    var width: CGFloat = 0 {
        didSet { isWide = width > 600 }
    }

    private(set) var isWide: Bool = false
}

struct RootView: View {
    @State private var viewport = ViewportModel()

    var body: some View {
        ContentView()
            .environment(viewport)
            .onGeometryChange(for: CGFloat.self) { proxy in
                proxy.size.width
            } action: { newWidth in
                viewport.width = newWidth
            }
    }
}

struct ContentView: View {
    @Environment(ViewportModel.self) private var viewport

    var body: some View {
        // Only invalidates when isWide flips, not on every pixel.
        Text(viewport.isWide ? "Wide layout" : "Compact layout")
    }
}
```

The same shape applies to per-item coarsening in lists. When each row's appearance depends on scroll position, the naive fix (store the offset on an `@Observable` model and have rows read it raw) does not actually reduce invalidations. Each row still depends on `offset`, so SwiftUI invalidates all visible rows on every frame, just routed through the model instead of the environment. The work to do is **at the model**: give each item its own `@Observable` object whose properties track only that item's derived state. Because Observation tracks at the property level, a row that reads `itemModel.isVisible` invalidates only when *that specific property* changes, not when a sibling's property changes. This achieves true per-item isolation: each row invalidates at most twice (once on enter, once on leave), regardless of list size or scroll speed.

```swift
// AVOID: Migrating to @Observable but rows still read the raw offset.
// `FeedItemView` invalidates on every scroll frame just like before —
// the cost moved from environment propagation to observation tracking,
// but the per-frame body invalidation count is unchanged.
@MainActor
@Observable
final class FeedModel {
    var offset: CGFloat = 0
}

struct FeedItemView: View {
    let index: Int
    @Environment(FeedModel.self) private var feed

    var body: some View {
        Text("Item \(index)")
            .opacity(feed.offset > CGFloat(index * -50) ? 1 : 0.3)  // reads raw offset
    }
}
```

```swift
// PREFER: Per-item @Observable model. Each row observes only its own
// `isVisible` property, so it invalidates at most twice (enter + leave)
// regardless of how many other items change visibility.
@MainActor
@Observable
final class FeedModel {
    private(set) var items: [ItemModel] = []

    func updateOffset(_ offset: CGFloat) {
        let visible = Set(computeVisibleIndices(for: offset))
        for (i, item) in items.enumerated() {
            item.isVisible = visible.contains(i)
        }
    }

    private func computeVisibleIndices(for offset: CGFloat) -> [Int] {
        // ... derive visible indices from offset, item height, viewport height.
    }
}

@MainActor
@Observable
final class ItemModel {
    let index: Int
    var isVisible = false
    init(index: Int) { self.index = index }
}

struct FeedItemView: View {
    @Environment(ItemModel.self) private var item

    var body: some View {
        Text("Item \(item.index)")
            .opacity(item.isVisible ? 1 : 0.3)
    }
}

// Parent wiring: inject a different ItemModel per row.
struct FeedView: View {
    @State private var feedModel = FeedModel()

    var body: some View {
        ScrollView {
            LazyVStack {
                ForEach(feedModel.items) { item in
                    FeedItemView()
                        .environment(item)
                }
            }
        }
    }
}
```

A common intermediate step is storing a shared `Set<Int>` of visible indices on the model and having each row call `.contains(index)`. This fires only on boundary crosses (not every frame), so it is a real improvement over the raw-offset approach. However, Observation tracks at the property level: mutating the set invalidates *every* row that read it, not just the 1-2 rows whose visibility actually changed. The per-item model above achieves true O(1) invalidation per visibility change.

The discriminating question is *"what's the granularity of the value the view actually reads?"* — not "is the value held in `@Observable`?" `@Observable` is a precondition for per-property tracking; coarsening is what reduces the per-frame body-invalidation count.

A note on framework alternatives: for purely visual effects driven by scroll position (opacity, scale, rotation tied to position in the viewport), `scrollTransition` and `visualEffect(in:)` push the per-frame work to the renderer and skip body re-evaluation entirely. They are the right tool when nothing outside the row's visual styling depends on the scroll position. They do not replace the `@Observable` + coarsening pattern when the scroll-derived state needs to drive *non-rendering* logic (model updates, prefetches, network calls, sibling-view state). When in doubt: if you'd otherwise propagate the value via `@State` / `@Environment` to drive logic, use the coarsened model; if you only need a view modifier, use the framework modifier.

## Unstable Environment Default Values

An environment key's `defaultValue` is re-evaluated on every read that falls back to it whenever it's declared as a computed property. Two common ways to hit this:

- `@Entry` always wraps the default expression in a computed getter (for concurrency safety — the default doesn't need to be `Sendable`). So `@Entry var model = Model()` re-allocates `Model()` on every fallback read.
- A manual `EnvironmentKey` with a computed default — `static var defaultValue: T { Model() }` — re-runs the expression on every access for the same reason.

Either shape is a problem for **all reference types** (each call allocates a new heap instance, so reference equality fails) and more generally for **any default expression that can return a different result between calls**, even value types like `Date()`, `UUID()`, or random numbers.

Any ancestor write to *any* environment key causes descendants to re-read theirs. A reader that falls back to an unstable default gets a different value than before and invalidates, even though nothing relevant to it changed.

`Equatable` is a fast path, not a prerequisite. Even without `Equatable` conformance, SwiftUI treats two instances with matching fields as equal. This means a value-typed default is stable as long as each stored property resolves to the same value on every call — enum cases, `nil`, fixed literals, and references that point to the same instance across calls all qualify. What breaks stability is any stored property that differs between calls: a fresh reference allocation (`struct Foo { let model = Model() }` — each `Foo()` creates a new `Model`, so two `Foo` instances' `model` fields are different pointers) or a captured runtime value (`Date()`, `UUID()`). The operative test is "does the expression return a different result between calls," not "does the type conform to `Equatable`." (Closures are governed by the separate closures-in-env rule earlier in this section — that rule forbids them outright, regardless of whether they appear at a default or a write site.)

Stable defaults don't hit this: a fixed literal, a `nil` optional default, or a `let`-backed value (either an `@Entry` backed by a `static let`, or a manual key with `static let defaultValue`) all return the same value on every read.

The invalidation only materializes when a reader actually falls back to the default. If every reader has a value injected upstream via `.environment(\.key, …)`, the unstable default is latent — fixing it is still correct (a future maintainer adding a reader without upstream injection, or removing an existing injection, would silently surface the problem), but it's a regression guard rather than a current-cost recovery. When reviewing, distinguish the two: a live issue has readers falling back and paying invalidation now; a latent one has every reader currently covered by an upstream injection. The fix shape is identical either way, but framing — urgency, priority, how you describe it in a PR — isn't.

### EXAMPLE: @Entry with an unstable default

```swift
@Observable class Model {}

extension EnvironmentValues {
    @Entry var model = Model()
    @Entry var counter = 0
}

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

    var body: some View {
        VStack {
            Button("++") { counter += 1 }
            RowContent()
        }
        .environment(\.counter, counter)
    }
}

struct RowContent: View {
    @Environment(\.model) private var model

    var body: some View {
        // Every "++" invalidates this view because `model`'s default
        // getter constructs a new `Model()` on every read.
        let _ = Self._printChanges()
        Text("Row Content")
    }
}
```

A value-typed re-evaluating default has the same problem — `@Entry var lastRefreshed = Date()` produces a different timestamp on each read, and readers invalidate on every unrelated env update for the same reason.

### Not a fix: Conforming the default type to Equatable

Making the unstable type conform to `Equatable` with a trivial or degenerate `==` can suppress the invalidation symptom, but the default expression still re-evaluates on every read. A new instance is allocated each time, any side effects in the initializer still fire, and two readers that fall back to the default get different instances — so observation changes on one don't propagate to the other.

```swift
// AVOID: Equatable masks invalidation without fixing the underlying re-evaluation.
@Observable final class Model: Equatable {
    init() { print("init") }  // still fires on every unrelated env write
    var id = 0
    static func == (lhs: Model, rhs: Model) -> Bool { lhs.id == rhs.id }
}

extension EnvironmentValues {
    @Entry var model = Model()
}
```

Use Options A, B, or C below so the default itself is stable.

### Not a fix: Defensive memoization of already-stable defaults

If the default satisfies the operative test above — every field resolves to the same value across calls (literals, `nil`, module-level `let` references, including struct fields that capture a module-level `let`) — leave it alone. Don't recommend `static let` backing, an `Optional` wrap, or a "regression guard" rewrite "for clarity." Don't recommend adding `Equatable` conformance "for safety" either — the default is already byte-equal on every call without it (`Equatable` is a fast path, not a prerequisite), and the prior "Not a fix: Conforming the default type to Equatable" section explains why `Equatable` doesn't fix unstable defaults anyway. A defensive refactor is noise that implies a bug where there isn't one and adds an indirection without changing behavior. Apply Options A/B/C only when the operative test actually fails.

Reviewers commonly misfire on two shapes — call them out specifically and leave them alone:

- **A struct field holds a reference, but the reference comes from a stable source.** A class type in the struct is *not* a red flag on its own. What matters is whether the source of the reference is stable. A module-level `let`, a `static let`, or a dependency-injected instance held by the caller all produce the same pointer on every call to the default expression.
- **A struct constructed inline in `@Entry` with deterministic argument values.** Enum cases with no associated values, `nil`, literals, and the stable references above all qualify. The struct itself doesn't need to be `Equatable` — SwiftUI compares field-by-field.

```swift
// FINE: stable default — do not "fix" this.
// `sharedLogger` is a module-level `let`, so every call to
// `RequestContext(logger: sharedLogger, retryBudget: 3)` captures
// the same `Logger` pointer; `retryBudget: 3` is a literal.
// Two default-evaluated `RequestContext` instances are byte-equal,
// regardless of whether `RequestContext` conforms to `Equatable`.

final class Logger { func log(_ message: String) {} }

struct RequestContext {
    let logger: Logger
    let retryBudget: Int
}

private let sharedLogger = Logger()

extension EnvironmentValues {
    @Entry var requestContext = RequestContext(logger: sharedLogger, retryBudget: 3)
}
```

```swift
// FINE: stable default — do not "fix" this.
// `.standard` is an enum case with no associated values and `nil`
// for `PresentationHandler?` is a constant. Two `ViewContext(mode: .standard, presentation: nil)`
// calls produce byte-equal instances. `Equatable` conformance is
// not required for SwiftUI to dedupe them.

protocol PresentationHandler { func dismiss() }

struct ViewContext {
    enum Mode { case standard, compact, expanded }
    let mode: Mode
    let presentation: PresentationHandler?
}

extension EnvironmentValues {
    @Entry var viewContext = ViewContext(mode: .standard, presentation: nil)
}
```

Contrast with the unstable shape — same struct skeleton, but the default expression *constructs* a fresh reference on every call:

```swift
// AVOID: unstable default. `RequestContext()` runs the `logger = Logger()`
// default initializer on every fallback read, so two default-evaluated
// instances carry different `logger` pointers.

struct RequestContext {
    let logger = Logger()      // fresh allocation per init
    let retryBudget = 3
}

extension EnvironmentValues {
    @Entry var requestContext = RequestContext()
}
```

The discriminating question is always *"does this default expression return a different result between calls?"* — not "does this struct contain a class?" and not "is this type `Equatable`?"

### FIX: Unstable environment default values

These options apply to both the reference-type case and any fresh-value case (`Date()`, `UUID()`, etc.) — substitute the unstable expression as needed.

**Option A: Back the default with a stable property**

Declare a `static let` next to the `@Entry` declaration and reference it from the initializer. The macro still wraps the expression in a computed getter, but the expression now resolves to the same memoized value on every read.

```swift
@Observable class Model {}

extension EnvironmentValues {
    @Entry var model = _defaultModel
    private static let _defaultModel = Model()
    @Entry var counter = 0
}

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

    var body: some View {
        VStack {
            Button("++") { counter += 1 }
            RowContent()
        }
        .environment(\.counter, counter)
    }
}

struct RowContent: View {
    @Environment(\.model) private var model

    var body: some View {
        // `_defaultModel` is a `static let`, so every read returns the
        // same instance. Updating `\.counter` no longer invalidates.
        let _ = Self._printChanges()
        Text("Row Content")
    }
}
```

**Option B: Declare the `EnvironmentKey` manually**

Skip `@Entry` for this key and write the conformance by hand. Use `static let defaultValue` — a stored constant, evaluated once and memoized. Do not use `static var defaultValue: T { … }`; a computed property re-evaluates on every read, giving you the same problem the macro has.

```swift
private struct ModelKey: EnvironmentKey {
    static let defaultValue = Model()
}

extension EnvironmentValues {
    var model: Model {
        get { self[ModelKey.self] }
        set { self[ModelKey.self] = newValue }
    }
}
```

`ContentView` and `RowContent` are unchanged from Option A.

**Option C: Use an optional with a `nil` default**

An `@Entry` with an `Optional` type and no initializer defaults to `nil` — a constant. Callers must handle the optional, but the default is stable across every read.

```swift
extension EnvironmentValues {
    @Entry var model: Model?
}
```

`ContentView` and `RowContent` are unchanged from Option A; `model` is now an optional at call sites.

**Diagnostic — sentinel values in readers signal Option C.** When you flag an unstable default, look at what readers do with the value. If a reader checks for an "empty" or "default" state with something like `value.id.isEmpty`, `value.count == 0`, `value == .none`, `value === sentinelInstance`, or compares against the same default the `@Entry` constructs — that check *is* an absence test in disguise. The reader is encoding "no value here" as a magic value. The honest expression of that intent is `Optional` + `if let`, not a sentinel field on a real instance. Picking Option A or B in this case fixes the invalidation but leaves a worse design in place: the sentinel survives, every caller has to know the magic value, and the type system can't tell you when you forgot to check. Pick Option C and update readers to branch on the optional.

```swift
// Before: unstable default, sentinel-as-absence in reader.
@Observable final class EditingSession {
    var documentId: String
    init(documentId: String) { self.documentId = documentId }
}

extension EnvironmentValues {
    @Entry var editingSession = EditingSession(documentId: "")  // unstable + sentinel default
}

struct DocumentArea: View {
    @Environment(\.editingSession) private var session
    var body: some View {
        if session.documentId.isEmpty {            // sentinel-as-absence
            Text("No document open")
        } else {
            Text("Editing: \(session.documentId)")
        }
    }
}

// After: Option C — absence becomes an Optional, sentinel disappears.
extension EnvironmentValues {
    @Entry var editingSession: EditingSession?
}

struct DocumentArea: View {
    @Environment(\.editingSession) private var session
    var body: some View {
        if let session {                            // honest absence test
            Text("Editing: \(session.documentId)")
        } else {
            Text("No document open")
        }
    }
}
```

**Choosing between A, B, and C:** Run the diagnostic above first. If readers contain a sentinel check, pick **Option C** and rewrite the readers to use `if let` — fixing the unstable default *and* removing the sentinel design. If readers always use the value as a real instance (no absence checks, no comparisons against magic defaults), the default itself is semantically a real value — pick **Option A** when you want to keep `@Entry` syntax and the default expression is short, or **Option B** when the manual `EnvironmentKey` pattern reads more clearly (typically when the default is complex, used from multiple places, or benefits from living on the key type rather than inline on the `@Entry` declaration). Don't list A/B/C as parallel choices and leave the pick to the reader — make the call based on what the readers actually do.

## Unused @Environment Reads

Declaring `@Environment(\.someKey)` on a view subscribes that view to changes in `\.someKey`, even if the view's `body` never references the wrapped value. When `\.someKey` changes, SwiftUI re-evaluates the view — and when the body doesn't depend on the key, that re-evaluation is pure overhead. The same applies to `@FocusedValue`.

The type-based form `@Environment(Model.self)` — used with `@Observable` models — behaves differently. Observation tracks reads at the **property** level, so declaring `@Environment(Model.self) var model` without reading any property of `model` in the body registers no property-level dependency; changes to `model`'s properties don't re-evaluate the view. An unused type-form declaration carries no live invalidation cost unless the env entry for that model has an unstable default (in which case the unstable-default section above is what applies, not a read-site problem).

When reviewing, walk each view's `@Environment` / `@FocusedValue` declarations and check whether the wrapped property is referenced in the body (directly, via the `_propertyName` projected form, or through any computed property or method the body calls). If nothing references it, delete the declaration:

- **KeyPath form (`@Environment(\.key)`, `@FocusedValue(\.key)`)**: removing is an active perf fix. Every ancestor write to `\.key` is currently invalidating the view.
- **Type form (`@Environment(Model.self)`)**: removing is dead-code cleanup. There's no live invalidation cost unless the underlying env has an unstable default.

```swift
// AVOID: declared but never read in body
struct BadgeView: View {
    @Environment(\.theme) private var theme   // never referenced below
    let label: String

    var body: some View {
        Text(label)
    }
}
```

```swift
// PREFER: remove the unused subscription
struct BadgeView: View {
    let label: String

    var body: some View {
        Text(label)
    }
}
```

# ForEach

`ForEach` uses identity to match up elements across body evaluations. When SwiftUI re-runs a parent's `body`, it diffs the previous collection of identifiers against the new one to figure out which rows were inserted, removed, moved, or merely updated. The identity of each element is the anchor that lets SwiftUI:

- Preserve `@State`, focus, selection, and scroll position for a row that merely moved or whose content changed.
- Animate insertions, removals, and reorders correctly. A row keeps its on-screen presence as it moves; a new row fades or slides in; a removed row transitions out.
- Avoid rebuilding subtrees unnecessarily. Stable identity lets SwiftUI reuse the existing view for an element whose data changed rather than tearing it down and creating a fresh one.

If identity is unstable, none of this works: state resets, animations break into abrupt replacements, and performance suffers as SwiftUI rebuilds subtrees that could have been reused.

The rule of thumb: the identity of a `ForEach` element must be **stable** (the same element has the same id across body evaluations, even if its position in the collection changes) and **unique** (no two distinct elements share an id in the same `ForEach`).

## Applies to other data-driven initializers

Everything in this document applies to any SwiftUI API that takes a `RandomAccessCollection` of data plus an `id:` key path (or `Identifiable` elements) and internally behaves like `ForEach`. The most common ones:

- `List(_:id:rowContent:)` and `List(_:rowContent:)` (the `Identifiable` overload).
- `List(_:id:selection:rowContent:)` and related selection-aware overloads.
- `Table(_:)` / `Table(_:selection:)` and their `id:` overloads.
- `OutlineGroup(_:id:children:content:)` and `List(_:children:rowContent:)` (outline variants).
- `Picker` overloads that iterate a data collection, such as `Picker(_:selection:content:)` used with `ForEach` inside.
- `DisclosureGroup` when paired with `ForEach` in its content.

Whenever you see one of these taking a collection directly, read "id per element" the same way you would for `ForEach`: stable, unique, and independent of position or mutable content.

## Avoid collection indices as identity

Using a collection's indices, or `.self` on an index, as the identifier is the most common anti-pattern. Indices describe a position, not an element. As soon as the collection is reordered, inserted into, or filtered, the same index now refers to a different element - and SwiftUI has no way to tell.

```swift
// AVOID: Using indices as identity.
// When `items` is reordered or an element is inserted, every id from the
// insertion point onward now maps to a different element. SwiftUI sees
// "the element at id 3 changed" rather than "element B moved from 3 to 4",
// so row state resets and moves animate as replacements.
struct ItemList: View {
    @State private var items: [Item] = []

    var body: some View {
        List {
            ForEach(items.indices, id: \.self) { index in
                ItemRow(item: items[index])
            }
        }
    }
}
```

```swift
// PREFER: Identify each element by a property that travels with the element.
ForEach(items, id: \.id) { item in
    ItemRow(item: item)
}
```

Seeing `.indices`, `\.offset`, or `id: \.self` on anything other than a value that is genuinely identity-like (e.g. a `String` that is already a unique key) is a signal that identity is being derived from position. The fix is to identify elements by a property of the element itself.

### `.enumerated()` is fine - the index just shouldn't be the id

Using `.enumerated()` is not itself an anti-pattern. It is a reasonable way to get the index alongside each element, for example when a row needs to display its position. The anti-pattern is specifically using the index as the id. Keep the element's own identity as the id and treat the index as ordinary row data:

```swift
// AVOID: `.enumerated()` with the offset as id.
// Same failure mode as `items.indices`: the id is the position, not the element.
ForEach(items.enumerated(), id: \.offset) { index, item in
    ItemRow(number: index + 1, item: item)
}
```

```swift
// PREFER: `.enumerated()` is fine; the id comes from the element, and the
// index is just row data passed to the row view.
ForEach(items.enumerated(), id: \.element.id) { index, item in
    ItemRow(number: index + 1, item: item)
}
```

### `.enumerated()` and `RandomAccessCollection`

As of Swift 6.1, the sequence returned by `.enumerated()` conditionally conforms to `Collection`, `BidirectionalCollection`, and `RandomAccessCollection` when the base collection does. `ForEach` requires its data to be a `RandomAccessCollection`, so on Swift 6.1 and later you can pass `items.enumerated()` directly - no `Array(...)` wrapper is needed. On earlier toolchains the wrapper is still required. Favor the direct form in new code; it avoids an eager copy of the collection on every body evaluation.

## Don't create a new id on every body evaluation

An `Identifiable` type whose `id` is generated fresh each time `body` runs looks like it has identity, but every body evaluation produces a brand-new identifier. From `ForEach`'s point of view, the entire collection was replaced on every update.

```swift
// AVOID: Constructing the items inside `body`. Each call to `Item(title:)`
// initializes a new UUID, so every body evaluation produces an entirely
// new set of ids. ForEach reads it as "the whole collection was replaced":
// state resets, rows flicker, animations degenerate into full replacements.
// The `let id = UUID()` default itself is fine - the bug is creating the
// values somewhere that doesn't outlive `body`.
struct Item: Identifiable {
    let id = UUID()
    var title: String
}

struct ContentView: View {
    let titles: [String]

    var body: some View {
        List {
            ForEach(titles.map { Item(title: $0) }) { item in
                Text(item.title)
            }
        }
    }
}
```

A `let id = UUID()` default works as long as the value itself is stored somewhere durable (a `@State`, an `@Observable` model, a database row); it becomes a bug the moment the value is reconstructed on every body pass. The fix is to ensure the id is tied to something that persists across body evaluations. If the source data has a natural key (a database id, a file URL, a server-assigned id), use that. If you must synthesize an id, do it once, in storage that outlives `body` - typically the model layer.

```swift
// PREFER: Derive identity from a property that is itself immutable for
// a given element - a server-assigned id, a file URL, a catalog SKU.
// Because the property is `let`, the computed `id` can't change as the
// element is edited.
struct Document: Identifiable {
    let url: URL              // where the file lives; assigned at creation
    var displayName: String   // user-editable

    var id: URL { url }
}
```

```swift
// PREFER: Create the UUID once, in the model that owns the items, and keep
// it across updates. `body` just reads the already-stable ids.
@MainActor
@Observable
final class ItemStore {
    var items: [Item] = []

    func add(title: String) {
        items.append(Item(id: UUID(), title: title))
    }
}

struct Item: Identifiable {
    let id: UUID
    var title: String
}
```

## Prefer `Identifiable` conformance

`ForEach` accepts an explicit `id:` key path, but conforming the element type to `Identifiable` is the idiomatic choice when the element has a natural identity. It lets callers write `ForEach(items)` without repeating the key path, documents the identity at the type level, and makes the type usable with other SwiftUI APIs that expect `Identifiable` (`List`, `sheet(item:)`, `confirmationDialog(..., presenting:)`, navigation value types, etc.).

```swift
// PREFER: Identifiable conformance; the identity is declared once on the type.
struct Item: Identifiable {
    let id: UUID
    var title: String
}

ForEach(items) { item in
    ItemRow(item: item)
}
```

```swift
// Acceptable when the element type isn't yours to change, or when the id
// lives on a different type (e.g. a value type wrapping a reference).
ForEach(items, id: \.serverID) { item in
    ItemRow(item: item)
}
```

Don't conform types to `Identifiable` just to satisfy `ForEach` if there is no meaningful notion of identity for the type. In that case, pass an explicit key path to the property that acts as identity in this context.

## Keep the id cheap to hash

`ForEach` hashes and compares element ids frequently - on every diff, which happens any time the enclosing view's `body` re-evaluates the collection. If the id type is expensive to hash, that cost is paid on every update and scales with the size of the collection.

The common anti-pattern is using the entire element as the id - either `id: \.self` on a large `Hashable` struct, or an `id` property that returns the whole value. The compiler-synthesized `Hashable` conformance feeds every stored property into the hasher; for a struct that holds long strings, nested collections, or many fields, each hash does real work, and the work is repeated for every row on every update.

```swift
// AVOID: id is the whole struct. Hashing each row walks every field on every
// diff - long strings, nested arrays, the lot. Cost scales with both the
// collection size and the per-element field count.
struct Article: Hashable {
    let title: String
    let body: String        // potentially large
    let tags: [String]
    let author: Author
    let publishedAt: Date
}

ForEach(articles, id: \.self) { article in
    ArticleRow(article: article)
}
```

```swift
// PREFER: id is a small, cheap-to-hash property that uniquely identifies
// the element. The full struct is still passed to the row view; only the
// id is hashed during diffing.
struct Article: Identifiable, Hashable {
    let id: UUID
    let title: String
    let body: String
    let tags: [String]
    let author: Author
    let publishedAt: Date
}

ForEach(articles) { article in
    ArticleRow(article: article)
}
```

Good ids are small primitives: `UUID`, `Int`, a short `String` key, a `URL`. They hash in constant time independent of how large the underlying element is. If the element has a natural key (a database id, a server-assigned id, a file URL), use it; otherwise synthesize one and store it on the element.

The fix is to pick the right id, not to touch the `Hashable` conformance. Leave it as it is - it may be used elsewhere (selection, sets, dictionary keys, navigation values), and removing it is unrelated to the diffing cost.

## Identity must outlive the view that renders the `ForEach`

`ForEach` assumes that an element's identity is stable for at least as long as the view rendering the `ForEach` is on screen. If an element's id changes while the enclosing view is still alive, SwiftUI interprets it as "the old element was removed and a new one inserted", which drops the row's state and plays removal/insertion animations instead of an in-place update.

The common trap is deriving the id from a property that is mutated in place (for example, computing `id` from the current title, then editing the title). The edit changes the id, the row is destroyed and recreated mid-edit, and focus, selection, and any per-row `@State` are lost.

```swift
// AVOID: id derived from a mutable property that edits will change.
// Typing in the row's text field renames the item, which changes its id,
// which makes ForEach think the row was removed and a new one inserted.
// The text field loses focus on every keystroke.
struct Item: Identifiable {
    var id: String { title }
    var title: String
}
```

```swift
// PREFER: id is independent of any mutable content. Editing `title` leaves
// identity untouched, so the row keeps its state and focus.
struct Item: Identifiable {
    let id: UUID
    var title: String
}
```

When in doubt, ask: "If I edit this element in place, does its id change?" If yes, identity is tied to content and will break on every edit. The id should change only when the element is genuinely a different element, not when its data is updated.

## Don't sort or filter inline in `ForEach`

The collection passed to `ForEach` is evaluated every time the enclosing view's `body` runs. If that expression is a non-trivial transformation - `sorted`, `filter`, `map` that rebuilds elements, grouping, deduplication - the work is repeated on every invalidation, even ones that have nothing to do with the list contents (a parent state change, an environment update, a window resize).

```swift
// AVOID: Sorting and filtering inside the ForEach argument.
// Every body evaluation re-runs `filter` and `sorted` over the full array,
// even when the change that invalidated this view has nothing to do with
// `items` or `searchText`.
struct ItemList: View {
    let items: [Item]
    let searchText: String

    var body: some View {
        List {
            ForEach(
                items
                    .filter { $0.title.localizedCaseInsensitiveContains(searchText) }
                    .sorted { $0.title < $1.title }
            ) { item in
                ItemRow(item: item)
            }
        }
    }
}
```

Cache the derived collection on the model or in view state, and recompute it only when an input actually changes. An `@Observable` model is the natural home: recompute in a `didSet` or in the mutating entry points, and let the view read the already-sorted, already-filtered array.

```swift
// PREFER: The model owns the derived collection and updates it only when
// its inputs change. The view reads a prepared array; `body` does no work
// beyond iterating.
@MainActor
@Observable
final class ItemListModel {
    var items: [Item] = [] {
        didSet { recomputeVisibleItems() }
    }

    var searchText: String = "" {
        didSet { recomputeVisibleItems() }
    }

    private(set) var visibleItems: [Item] = []

    private func recomputeVisibleItems() {
        visibleItems = items
            .filter { $0.title.localizedCaseInsensitiveContains(searchText) }
            .sorted { $0.title < $1.title }
    }
}

struct ItemList: View {
    let model: ItemListModel

    var body: some View {
        List {
            ForEach(model.visibleItems) { item in
                ItemRow(item: item)
            }
        }
    }
}
```

If the derived collection is genuinely view-local (e.g. a local filter box that doesn't belong in the model), cache it in `@State` and update it when inputs change via `onChange(of:)` rather than recomputing in `body`. The principle is the same: compute once per input change, not once per body evaluation.

Cheap transformations - a small slice, `prefix(n)`, reading an already-prepared array, a trivial map to a struct - are fine inline. The rule targets work whose cost scales with the collection, or that allocates new elements.

## Prefer unary row views in `List`

`List` needs the identity of every row up front: it has to materialize the full id set to diff against the previous update. When each row is a single view per element, SwiftUI can template the row id from the `ForEach` element's id alone, without running each row's `body`. That fast path is what makes a long `List` cheap.

A row's final id combines the explicit id from `ForEach` with a bit of structural identity - roughly, a marker for which top-level view inside the row was produced. If the row body produces a single top-level view, structural identity is constant and each row's id is fully determined by the element's id. If the row body branches between different top-level shapes (a bare `switch`, a top-level `if`/`else`), the structural part varies per row. SwiftUI can't template from the first row because it can't assume subsequent rows took the same branch; it falls back to evaluating every row's body just to compute ids, and update cost scales with the number of rows.

```swift
// AVOID: The row view is "multi" - the top-level `switch` makes each row's
// structural identity depend on which case ran. To compute ids, SwiftUI
// has to evaluate every row's body, even for long lists.
struct ItemRow: View {
    var item: Item

    var body: some View {
        switch item.kind {
        case .plain:       Text(item.title)
        case .highlighted: Text(item.title).bold()
        case .disabled:    Text(item.title).foregroundStyle(.secondary)
        }
    }
}

struct ItemList: View {
    let items: [Item]

    var body: some View {
        List {
            ForEach(items) { item in
                ItemRow(item: item)
            }
        }
    }
}
```

```swift
// PREFER: Wrap the branching content in a container so the row is "unary"
// - one top-level view regardless of which case ran. SwiftUI can template
// ids from the ForEach without walking every row.
struct ItemRow: View {
    var item: Item

    var body: some View {
        VStack {
            switch item.kind {
            case .plain:       Text(item.title)
            case .highlighted: Text(item.title).bold()
            case .disabled:    Text(item.title).foregroundStyle(.secondary)
            }
        }
    }
}
```

Any single-root container works - `VStack`, `HStack`, `ZStack`, or a custom wrapper view. The point is to turn N possible top-level views into one.

Don't "fix" this by flattening the switch into a single shape with conditional modifiers (e.g. `Text(item.title).bold(item.kind == .highlighted)`). That happens to make this row unary only because all three cases produced the same top-level shape; it teaches the wrong lesson and breaks the moment cases produce structurally different views (Text vs Image vs Divider). Wrap the switch in a container instead.

### Unary vs multi views

A `View` is **unary** when its `body` produces a single top-level view (wrapped in `VStack`, `HStack`, `ZStack`, or another single-root container). It is **multi** when its body produces more than one top-level view, or branches between different top-level shapes. `Group` and `ForEach` are passthroughs, not containers - they do not make their contents unary. `Group { A(); B(); C() }` contributes the same three top-level views as writing `A(); B(); C()` directly.

For `List` rows, prefer unary. The fix is usually as simple as wrapping `body` in `VStack`.

### A top-level `if` without `else` is also multi

`ForEach`'s doc comment frames this fast path in terms of "constant number of views": each row's builder must produce the same number of top-level views for every element. A top-level `if` with no `else` produces either 0 or 1 views depending on the condition, so the count is not constant and the same fast path is defeated - SwiftUI has to evaluate every row's body to find out which elements contribute a row at all.

```swift
// AVOID: bare top-level `if` in a lazy container. The row is 0 or 1 view
// depending on `namedFont.name.count`, so the row builder does not produce
// a constant number of views and the List fast path is defeated.
ForEach(namedFonts) { namedFont in
    if namedFont.name.count != 2 {
        Text(namedFont.name)
    }
}
```

```swift
// PREFER: wrap in a single-root container so the row is always exactly one
// top-level view; the `if` becomes interior content.
ForEach(namedFonts) { namedFont in
    VStack {
        if namedFont.name.count != 2 {
            Text(namedFont.name)
        }
    }
}
```

If the intent is actually "skip this element", filter the collection before passing it to `ForEach` rather than producing a zero-view row. The wrapping fix is right when the row genuinely has optional content inside it; upstream filtering is right when some elements shouldn't be rows at all.

### Avoid `AnyView` as a `ForEach` row

`AnyView` erases the wrapped view's type, which erases its structural identity as well: SwiftUI can no longer tell from the type alone which shape a row produced. This defeats the same templating fast path as a top-level `switch` - the framework has to evaluate each row's body to find out what's inside.

```swift
// AVOID: Building rows as `AnyView`. Each row's structural identity is
// opaque to SwiftUI, so the List can't template ids and falls back to
// evaluating every row's body.
ForEach(items) { item in
    rowView(for: item) // returns AnyView
}

func rowView(for item: Item) -> AnyView {
    switch item.kind {
    case .plain:       return AnyView(Text(item.title))
    case .highlighted: return AnyView(Text(item.title).bold())
    case .disabled:    return AnyView(Text(item.title).foregroundStyle(.secondary))
    }
}
```

```swift
// PREFER: A concrete row view whose body uses `switch` or `if`/`else`
// inside a single-root container. The row's static shape is visible to
// SwiftUI, so it can template ids across the list.
struct ItemRow: View {
    var item: Item

    var body: some View {
        VStack {
            switch item.kind {
            case .plain:       Text(item.title)
            case .highlighted: Text(item.title).bold()
            case .disabled:    Text(item.title).foregroundStyle(.secondary)
            }
        }
    }
}

ForEach(items) { item in
    ItemRow(item: item)
}
```

The cost of `AnyView` is especially pronounced when it is the row of a `ForEach` feeding a `List`, because the loss of structural information scales with the number of rows. Prefer a concrete row view with `switch`/`if`/`else` inside a container over any design that reaches for `AnyView` to unify row types.

Don't "fix" this by replacing `AnyView` with a `@ViewBuilder` helper returning `some View`. The helper body is still a bare `switch` producing a `_ConditionalContent` tree — the row remains multi-shape and the same fast path is still defeated. Removing type erasure is only half the fix; the other half is wrapping the branching content inside a concrete row view with a single-root container.

### Diagnosing with `-LogForEachSlowPath`

To find non-constant row builders in an existing app, launch with:

```
-LogForEachSlowPath YES
```

SwiftUI logs each `ForEach` inside a lazy container (`List`, `LazyVStack`, and similar) whose row body produces a non-constant number of views. Use it to triage - the log points at the offending call sites so you can choose to refactor them.

# String Catalogs

Most projects localize through String Catalogs (`.xcstrings`). Each build syncs new strings from code into the catalog, but the catalog file must already exist — Xcode does not create one automatically. If a project already uses `.strings` or `.stringsdict` files, add new strings to the existing files rather than asking the user to migrate.

A project can use multiple String Catalogs and route strings to a specific one with the `tableName` parameter — useful when it makes sense to keep groups of strings separate (e.g., per feature or module).

```swift
Text("Explore", tableName: "Navigation",
     comment: "Tab bar item title for the Explore screen.")
```

# Bundle for Swift Packages and Frameworks

Apps, app extensions, and XPC services are their own main bundle, so the `bundle` parameter can be omitted. Frameworks and Swift packages need an explicit `bundle`; without one, SwiftUI looks up strings from `Bundle.main` and the lookup fails silently — the string appears unlocalized at runtime.

```swift
// AVOID: Inside a framework or Swift package, this searches the app's catalog.
Text("Save to Favorites")
```

```swift
// PREFER: #bundle resolves to the current target's bundle.
Text("Save to Favorites", bundle: #bundle,
     comment: "Button to bookmark a recipe.")
```

`#bundle` is the preferred form; `Bundle.module` and `Bundle(for: MyClass.self)` work but are older patterns.

# SwiftUI Views Localize String Literals Automatically

SwiftUI initializers that accept `LocalizedStringKey` (e.g., `Text`, `Button`, `.navigationTitle`) automatically treat string literals as localization keys. Do not wrap literals in `NSLocalizedString`, `String(localized:)`, or `LocalizedStringResource`.

```swift
// AVOID: Text already treats literals as LocalizedStringKey; wrapping
// also resolves the string eagerly, ignoring \.locale overrides.
Text(NSLocalizedString("start_workout", comment: ""))
Text(String(localized: "start_workout"))
```

```swift
// PREFER: Pass the string literal directly.
Text("start_workout")
```

Both opaque keys (`"start_workout"`) and natural-language strings (`"Start Workout"`) work as `LocalizedStringKey` values. Choose whichever convention the project uses consistently — with opaque keys, the source-language text is set in the String Catalog directly, not at the call site.

Use `Text(verbatim:)` to opt out of localization for a string literal — most often a debug label that interpolates a runtime value (e.g., `Text(verbatim: "Session: \(sessionID)")`), where the literal would otherwise be treated as a localization key. When the argument is already a `String` variable, `Text(value)` calls the `StringProtocol` overload and skips localization on its own — no `verbatim:` needed.

# Localizing Variables and Custom Types

When a `String` variable is passed to `Text`, the `StringProtocol` overload runs and the string is NOT localized. Wrapping the variable in `LocalizedStringKey(_:)` at the call site does not help either — Xcode cannot extract a literal from a runtime value, so the entry never lands in the catalog. To localize a value chosen from a known set of keys, model the set with a type that exposes `LocalizedStringResource`:

```swift
enum Category {
    case appetizers, mains, desserts
    var name: LocalizedStringResource {
        switch self {
        case .appetizers: "Appetizers"
        case .mains: "Mains"
        case .desserts: "Desserts"
        }
    }
}

Text(category.name)
```

When a view or view model exposes user-facing text, type the property as `LocalizedStringKey` or `LocalizedStringResource` instead of `String`. Every SwiftUI view that takes localized text accepts both, so deferring resolution costs nothing at the display site and preserves locale and bundle context end-to-end.

```swift
// AVOID: String properties lose localization context.
struct SectionHeader {
    let title: String
}
```

```swift
// PREFER: LocalizedStringResource keeps the string localizable.
struct SectionHeader {
    let title: LocalizedStringResource
}
```

# String Interpolation vs Concatenation

String interpolation preserves `LocalizedStringKey` and produces a format string in the catalog (e.g., `"Welcome, %@"`). Concatenation with `+` produces a `String` — the result is not localized.

```swift
// AVOID: + produces String, not LocalizedStringKey. Not localized.
Text("Error: " + statusMessage)
```

```swift
// PREFER: Interpolation preserves LocalizedStringKey.
Text("Error: \(statusMessage)")
```

Never glue separately localized fragments to form a sentence — word order varies across languages.

```swift
// AVOID: Sentence assembly breaks in languages with different word order.
Text(String(localized: "Created by")) + Text(" ") + Text(authorName)
```

```swift
// PREFER: A single string lets translators rearrange the structure.
Text("Created by \(authorName)")
```

# Casing

Bake the desired case into the string itself rather than transforming case at runtime via `.textCase(_:)`, `.localizedUppercase`, or `.localizedCapitalized`. A runtime transform forces the same casing decision across all translations, leaving translators no way to adjust per language.

```swift
// AVOID: forces the same casing on every translation.
Text("Section Header").textCase(.uppercase)

// PREFER: provide the desired case in the string itself.
Text("SECTION HEADER")
```

This applies to localized strings. Strings the user typed in should display as-is; you don't know what casing they intended. If a transform is unavoidable, prefer `.localizedUppercase` / `.localizedCapitalized`, which honor the user's locale (Turkish dotted/dotless I, German ß, etc.).

# Formatting Dates, Numbers, and Currencies

Use `Text`'s `format` parameter or `.formatted()` instead of `DateFormatter` or `NumberFormatter` with hardcoded format strings. Format styles adapt to the user's locale; hardcoded format strings do not. These overloads localize through the format style — they're not a bypass of localization, and the value itself doesn't produce a catalog entry. When the value is interpolated into a localized literal (e.g., `"Total: \(price, format: ...)"`), the surrounding literal still accepts a `comment:` as usual.

```swift
// AVOID: Hardcoded format does not adapt to locale.
let formatter = DateFormatter()
formatter.dateFormat = "MM/dd/yyyy"
Text(formatter.string(from: workout.date))
```

```swift
// PREFER: Format styles adapt to the user's locale automatically.
Text(workout.date, format: .dateTime.month().day().year())
```

Date field components (`.month()`, `.day()`, `.year()`) enable which fields appear; the locale determines output order — the chain order doesn't lock layout.

```swift
// AVOID: Hardcoded currency formatting.
Text("$\(product.price, specifier: "%.2f")")
```

```swift
// PREFER
Text(product.price, format: .currency(code: store.currencyCode))
```

For lists of strings, `Array.formatted()` inserts locale-correct separators and conjunctions instead of a hardcoded `joined(separator: ", ")`.

```swift
// AVOID
Text("Order: \(items.joined(separator: ", "))")
```

```swift
// PREFER
Text("Order: \(items.formatted())")
```

When `DateFormatter` is genuinely unavoidable, use `setLocalizedDateFormatFromTemplate(_:)` rather than assigning `dateFormat` directly — the template reorders fields per locale.

# Layout for Localization

Use `.leading` and `.trailing` instead of `.left` and `.right` — they flip for right-to-left locales; `.left` and `.right` don't.

```swift
// AVOID: .left does not flip for RTL languages.
Text(recipe.title)
    .frame(maxWidth: .infinity, alignment: .left)
```

```swift
// PREFER: .leading flips to the trailing edge in RTL locales.
Text(recipe.title)
    .frame(maxWidth: .infinity, alignment: .leading)
```

Do not hardcode frame widths or heights for text — translations vary in length and scripts vary in height. Use `ViewThatFits` when a layout might not fit longer translations.

```swift
// PREFER: ViewThatFits picks the first layout that fits.
ViewThatFits {
    HStack { actionButtons }
    VStack { actionButtons }
}
```

Use SwiftUI's text styles instead of fixed point sizes. Text styles let line height adapt per script; fixed point sizes can clip glyphs in tall scripts.

```swift
// AVOID: fixed point size locks line height.
Text("Welcome").font(.system(size: 17))

// PREFER: text styles let line height adapt per script.
Text("Welcome").font(.body)
```

# Reading the Current Locale

Use `@Environment(\.locale)` instead of `Locale.current` for locale-dependent logic in views — the environment respects preview overrides and per-view injection; `Locale.current` does not.

# String(localized:) Outside SwiftUI Views

When you need a localized `String` outside of SwiftUI views, use `String(localized:)`, not `NSLocalizedString`.

```swift
// AVOID
let title = NSLocalizedString("activity_summary", comment: "Dashboard header")
```

```swift
// PREFER
let title = String(localized: "activity_summary", comment: "Dashboard header")
```

Do not interpolate inside `NSLocalizedString` — Xcode extracts keys from literal strings at build time and cannot extract interpolated values. Use `String(localized:)` with interpolation instead; Xcode extracts the format string (e.g., `"reminder_body %@"`) and treats interpolated values as runtime arguments.

Prefer `String(localized:)` over `String(format:)` and `String.localizedStringWithFormat`. `String(format:)` always renders digits as 0–9 regardless of locale and is unsuitable for user-facing text; `String.localizedStringWithFormat` works when paired with `NSLocalizedString`, but `String(localized:)` is the modern API and the right default.

# LocalizedStringResource for Non-View Types

When a non-view type carries a user-facing string — a model object, a tip, a queued notification — use `LocalizedStringResource` instead of `String`. The string is resolved at display time, not creation time, so it honors the locale active when the value actually renders. Whenever a `String` would otherwise be passed between view models, modules, or into a view, `LocalizedStringResource` is the right type. Apply this when designing new types or changing user-facing text — don't sweep through existing `String` properties as part of unrelated edits.

```swift
// AVOID: Resolving at creation time loses the ability to display
// in a different locale later.
struct Tip {
    let headline: String
}
let tip = Tip(headline: String(localized: "Tip of the Day"))
```

```swift
// PREFER: LocalizedStringResource defers resolution to display time.
struct Tip {
    let headline: LocalizedStringResource
}
let tip = Tip(headline: "Tip of the Day")
```

# Comments for Translators

Add a `comment` describing the UI element and its purpose, especially for ambiguous strings. For interpolated strings, describe each placeholder by position — translators don't see Swift variable names.

```swift
// AVOID: "Edit" could be a noun or a verb — different translations.
Text("Edit")
```

```swift
// PREFER
Text("Edit", comment: "Toolbar button that enters editing mode for the list.")
```

```swift
// PREFER: refer to placeholders by position, not by Swift name.
Text("Completed \(count) of \(total)",
     comment: "Progress label — the first variable is finished items, the second is the total.")
```

Comments can also live in the String Catalog (per-string Comment field), equivalent to passing `comment:` at the call site — keep one source of truth per string.

# Conditional View Modifiers

Never write a conditional view modifier (sometimes called an `.if` modifier) that uses `@ViewBuilder` to switch between `transform(self)` and `self` based on a boolean. If you encounter an existing conditional view modifier in the codebase, do not remove or refactor it (doing so can change behavior and is out of scope), but when reviewing, point out that it may cause unexpected behavior and explain the alternatives below.

## Why conditional view modifiers are problematic

1. **View identity loss**: The `if`/`else` inside the modifier creates two branches with different view types. When the condition toggles, SwiftUI sees a completely different view rather than a modified version of the same view. This breaks structural identity.
2. **State reset**: Any `@State` in the view or its descendants resets when the condition changes, because SwiftUI treats the two branches as distinct views.
3. **Broken animations**: Instead of smoothly animating a property change, SwiftUI removes one view and inserts another, producing an abrupt transition.

```swift
// AVOID: A conditional view modifier extension.
// This destroys structural identity every time `condition` toggles.
extension View {
    @ViewBuilder
    func `if`<Content: View>(_ condition: Bool, transform: (Self) -> Content) -> some View {
        if condition {
            transform(self)
        } else {
            self
        }
    }
}

// Usage of the anti-pattern:
Text("Hello")
    .if(isHighlighted) { $0.foregroundStyle(.red) }
```

```swift
// PREFER: Use a ternary expression in the modifier argument.
// The view identity is preserved and SwiftUI animates the change smoothly.
Text("Hello")
    .foregroundStyle(isHighlighted ? .red : .primary)
```

## Reach for `AnyShapeStyle` to keep the ternary when styles differ

When the two styles are *different* `ShapeStyle` types (e.g. `.primary` is `HierarchicalShapeStyle`, `.tint` is `TintShapeStyle`), they won't unify into a single expression on their own. Do **not** fall back to an `if`/`else` `@ViewBuilder` branch that duplicates the view to switch styles; that introduce identity loss, state reset, and broken animations.

Wrap each branch in `AnyShapeStyle` so the ternary type-checks and the view stays a single, stable identity:

```swift
// AVOID: branching the whole view just to vary the style.
// `.primary` and `.tint` are different ShapeStyle types, so this splits
// one view into two, destroying structural identity when the condition flips.
if backgroundProminence == .increased {
    Text(verbatim: "\(id)").monospacedDigit().foregroundStyle(.primary)
} else {
    Text(verbatim: "\(id)").monospacedDigit().foregroundStyle(.tint)
}

// PREFER: erase to AnyShapeStyle and keep one view with a ternary.
Text(verbatim: "\(id)")
    .monospacedDigit()
    .foregroundStyle(
        backgroundProminence == .increased
            ? AnyShapeStyle(.primary)
            : AnyShapeStyle(.tint))
```

`AnyShapeStyle` is a value type, and erasing a shape style is cheap and idiomatic — it is **not** the discouraged view type-erasure (`AnyView`). Do not penalize or avoid `AnyShapeStyle`; using it to unify a ternary is the correct, preferred tool here. (When practical, picking a single style or modeling the choice without erasure is better still, but `AnyShapeStyle` is the right answer whenever the branches must produce different `ShapeStyle` types.)

### Do not assume a style ternary fails to compile from the style names alone

Mixing style *kinds* in a ternary does not automatically fail to type-check, and `AnyShapeStyle` is only needed when it actually does. A `Color` literal unifies with several built-in styles, so these compile as-is and must **not** be flagged as a type mismatch or "fixed" with `AnyShapeStyle`:

```swift
// COMPILES — leave it alone. The ternary unifies on its own.
.foregroundStyle(isHighlighted ? .yellow : .primary)
.foregroundStyle(isOn ? .red : .blue)
```

Reach for `AnyShapeStyle` only when the branches genuinely will not unify - two distinct non-`Color` styles, or a `Color` paired with a non-`Color` style:

```swift
// Does NOT compile: HierarchicalShapeStyle vs TintShapeStyle.
.foregroundStyle(isOn ? .primary : .tint)
// Does NOT compile: `.tint` resolves to a Color member that expects an argument here.
.foregroundStyle(isOn ? .yellow : .tint)
```

When uncertain, assume the ternary compiles rather than inventing a type-mismatch error. If it truly does not, the fix is `AnyShapeStyle`, never an `.if`/`@ViewBuilder` branch.

# Soft-Deprecated SwiftUI APIs

Generated from: iOS 27.0, macOS 27.0, tvOS 27.0, watchOS 27.0, visionOS 27.0

## Types

- `struct CarouselTabViewStyle : TabViewStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to VerticalTabViewStyle
- `struct MenuButton<Label, Content> : View where Label : View, Content : View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `Menu` instead.
- `struct ActionSheet` (iOS, macOS, tvOS, watchOS, visionOS)
  - use `View.confirmationDialog(title:isPresented:titleVisibility:presenting::actions:)`instead.
- `struct ColumnNavigationViewStyle : NavigationViewStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - replace styled NavigationView with NavigationSplitView
- `struct Alert` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use View.alert(_:isPresented:presenting:actions:) instead.
- `struct BorderedButtonMenuStyle : MenuStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use .menuStyle(.button) and .buttonStyle(.bordered).
- `struct RotationGesture : Gesture` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to RotateGesture
- `struct PresentationMode` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use EnvironmentValues.isPresented or EnvironmentValues.dismiss
- `struct MagnificationGesture : Gesture` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to MagnifyGesture
- `struct ContextMenu<MenuItems> where MenuItems : View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `contextMenu(menuItems:)` instead.
- `struct PullDownMenuButtonStyle : MenuButtonStyle` (iOS, macOS, visionOS)
  - Use `BorderedButtonMenuStyle` instead.
- `struct BorderlessPullDownMenuButtonStyle : MenuButtonStyle` (iOS, macOS, visionOS)
  - Use `BorderlessButtonMenuStyle` instead.
- `struct BorderlessButtonMenuButtonStyle : MenuButtonStyle` (iOS, macOS, visionOS)
  - Use `BorderlessButtonMenuStyle` instead.
- `struct DefaultMenuButtonStyle : MenuButtonStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `menuStyle(.automatic)` instead.
- `struct DefaultNavigationViewStyle : NavigationViewStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - replace styled NavigationView with NavigationStack or NavigationSplitView instead
- `struct BorderlessButtonMenuStyle : MenuStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use .menuStyle(.button) and .buttonStyle(.borderless).
- `struct DoubleColumnNavigationViewStyle : NavigationViewStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - replace styled NavigationView with NavigationStack or NavigationSplitView instead
- `struct NavigationView<Content> : View where Content : View` (iOS, macOS, tvOS, watchOS, visionOS)
  - use NavigationStack or NavigationSplitView instead
- `struct PopUpButtonPickerStyle : PickerStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the `menu` style instead.
- `struct StackNavigationViewStyle : NavigationViewStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - replace stack-styled NavigationView with NavigationStack
- `enum ContentSizeCategory : Hashable, CaseIterable, Sendable` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to DynamicTypeSize
- `enum ControlActiveState : Equatable, CaseIterable, Sendable` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `EnvironmentValues.appearsActive` instead.

## Protocols

- `protocol NavigationViewStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - replace styled NavigationView with NavigationStack or NavigationSplitView instead
- `protocol AnimatableModifier : Animatable, ViewModifier` (iOS, macOS, tvOS, watchOS, visionOS)
  - use Animatable directly
- `protocol MenuButtonStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `MenuStyle` instead.

## Initializers

- `TextField.init<V>(_ titleKey: LocalizedStringKey, value: Binding<V>, formatter: Formatter, onEditingChanged: @escaping (Bool) -> Void, onCommit: @escaping () -> Void)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:value:formatter:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `TextField.init<V>(_ titleKey: LocalizedStringKey, value: Binding<V>, formatter: Formatter, onEditingChanged: @escaping (Bool) -> Void)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:value:formatter:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `TextField.init<V>(_ titleKey: LocalizedStringKey, value: Binding<V>, formatter: Formatter, onCommit: @escaping () -> Void)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:value:formatter:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `TextField.init<S, V>(_ title: S, value: Binding<V>, formatter: Formatter, onEditingChanged: @escaping (Bool) -> Void, onCommit: @escaping () -> Void) where S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:value:formatter:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `TextField.init<S, V>(_ title: S, value: Binding<V>, formatter: Formatter, onEditingChanged: @escaping (Bool) -> Void) where S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:value:formatter:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `TextField.init<S, V>(_ title: S, value: Binding<V>, formatter: Formatter, onCommit: @escaping () -> Void) where S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:value:formatter:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `MenuButton.init(_ titleKey: LocalizedStringKey, @ContentBuilder content: () -> Content)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `Menu` instead.
- `TabView.init(selection: Binding<SelectionValue>?, @ContentBuilder content: () -> Content)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use TabContentBuilder-based TabView initializers instead
- `Slider.init<V>(value: Binding<V>, in bounds: ClosedRange<V> = 0...1, onEditingChanged: @escaping (Bool) -> Void = { _ in }, minimumValueLabel: ValueLabel, maximumValueLabel: ValueLabel, @ContentBuilder label: () -> Label) where V : BinaryFloatingPoint, V.Stride : BinaryFloatingPoint` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Slider(value:in:label:minimumValueLabel:maximumValueLabel:onEditingChanged:)
- `Slider.init<V>(value: Binding<V>, in bounds: ClosedRange<V>, step: V.Stride = 1, onEditingChanged: @escaping (Bool) -> Void = { _ in }, minimumValueLabel: ValueLabel, maximumValueLabel: ValueLabel, @ContentBuilder label: () -> Label) where V : BinaryFloatingPoint, V.Stride : BinaryFloatingPoint` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Slider(value:in:step:label:minimumValueLabel:maximumValueLabel:onEditingChanged:)
- `Slider.init<V>(value: Binding<V>, in bounds: ClosedRange<V> = 0...1, onEditingChanged: @escaping (Bool) -> Void = { _ in }, @ContentBuilder label: () -> Label) where V : BinaryFloatingPoint, V.Stride : BinaryFloatingPoint` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Slider(value:in:label:onEditingChanged:)
- `Slider.init<V>(value: Binding<V>, in bounds: ClosedRange<V>, step: V.Stride = 1, onEditingChanged: @escaping (Bool) -> Void = { _ in }, @ContentBuilder label: () -> Label) where V : BinaryFloatingPoint, V.Stride : BinaryFloatingPoint` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Slider(value:in:step:label:onEditingChanged:)
- `LinearProgressViewStyle.init(tint: Color)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use ``View/tint(_)`` instead.
- `CircularProgressViewStyle.init(tint: Color)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use ``View/tint(_)`` instead.
- `TextField.init(_ titleKey: LocalizedStringKey, text: Binding<String>, onEditingChanged: @escaping (Bool) -> Void, onCommit: @escaping () -> Void)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:text:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `TextField.init(_ titleKey: LocalizedStringKey, text: Binding<String>, onEditingChanged: @escaping (Bool) -> Void)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:text:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `TextField.init(_ titleKey: LocalizedStringKey, text: Binding<String>, onCommit: @escaping () -> Void)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:text:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `TextField.init<S>(_ title: S, text: Binding<String>, onEditingChanged: @escaping (Bool) -> Void, onCommit: @escaping () -> Void) where S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:text:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `TextField.init<S>(_ title: S, text: Binding<String>, onEditingChanged: @escaping (Bool) -> Void) where S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:text:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `TextField.init<S>(_ title: S, text: Binding<String>, onCommit: @escaping () -> Void) where S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed TextField.init(_:text:onEditingChanged:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter. Use FocusState<T> and View.focused(_:equals:) for functionality previously provided by the onEditingChanged parameter.
- `InsetListStyle.init(alternatesRowBackgrounds: Bool)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the `.inset` style with the `.alternatingRowBackgrounds()` view modifier
- `ToolbarItem.init(id: String, placement: ToolbarItemPlacement = .automatic, showsByDefault: Bool, @ContentBuilder content: () -> Content)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the CustomizableToolbarContent/defaultCustomization(_:options) modifier with a value of .hidden
- `Section.init(header: Parent, footer: Footer, @ContentBuilder content: () -> Content)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Section(content:header:footer:)
- `Section.init(footer: Footer, @ContentBuilder content: () -> Content)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Section(content:footer:)
- `Section.init(header: Parent, @ContentBuilder content: () -> Content)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Section(content:header:)
- `GroupBox.init(label: Label, @ContentBuilder content: () -> Content)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to GroupBox(content:label:)
- `InsetTableStyle.init(alternatesRowBackgrounds: Bool)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the `.inset` style with the `.alternatingRowBackgrounds()` view modifier
- `Picker.init(selection: Binding<SelectionValue>, label: Label, @ContentBuilder content: () -> Content)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Picker(selection:content:label:)
- `ScrollView.init(_ axes: Set = .vertical, showsIndicators: Bool = true, @ContentBuilder content: () -> Content)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the ScrollView(_:content:) initializer and the scrollIndicators(:_) modifier
- `NavigationLink.init(destination: Destination, @ContentBuilder label: () -> Label)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Pass a closure as the destination
- `NavigationLink.init(_ titleKey: LocalizedStringKey, destination: Destination)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Pass a closure as the destination
- `NavigationLink.init<S>(_ title: S, destination: Destination) where S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Pass a closure as the destination
- `NavigationLink.init(destinationName: String, @ContentBuilder label: () -> Label)` (iOS, macOS, tvOS, watchOS, visionOS)
  - use NavigationLink(value:label:)
- `NavigationLink.init(destinationName: String, isActive: Binding<Bool>, @ContentBuilder label: () -> Label)` (iOS, macOS, tvOS, watchOS, visionOS)
  - use NavigationLink(value:label:)
- `NavigationLink.init<V>(destinationName: String, tag: V, selection: Binding<V?>, @ContentBuilder label: () -> Label) where V : Hashable` (iOS, macOS, tvOS, watchOS, visionOS)
  - use NavigationLink(value:label:)
- `SecureField.init(_ titleKey: LocalizedStringKey, text: Binding<String>, onCommit: @escaping () -> Void)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed SecureField.init(_:text:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter.
- `SecureField.init<S>(_ title: S, text: Binding<String>, onCommit: @escaping () -> Void) where S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed SecureField.init(_:text:). Use View.onSubmit(of:_:) for functionality previously provided by the onCommit parameter.
- `BorderedButtonStyle.init(tint: Color)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use ``View/tint(_)`` instead.
- `Color.init(_ color: UIColor)` (iOS, tvOS, watchOS, visionOS)
  - Use Color(uiColor:) when converting a UIColor, or create a standard Color directly
- `BorderedListStyle.init(alternatesRowBackgrounds: Bool)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the `.bordered` style with the `.alternatingRowBackgrounds()` view modifier
- `Stepper.init(onIncrement: (() -> Void)?, onDecrement: (() -> Void)?, onEditingChanged: @escaping (Bool) -> Void = { _ in }, @ContentBuilder label: () -> Label)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Stepper(label:onIncrement:onDecrement:onEditingChanged:)
- `Stepper.init<V>(value: Binding<V>, step: V.Stride = 1, onEditingChanged: @escaping (Bool) -> Void = { _ in }, @ContentBuilder label: () -> Label) where V : Strideable` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Stepper(value:step:label:onEditingChanged:)
- `Stepper.init<V>(value: Binding<V>, in bounds: ClosedRange<V>, step: V.Stride = 1, onEditingChanged: @escaping (Bool) -> Void = { _ in }, @ContentBuilder label: () -> Label) where V : Strideable` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to Stepper(value:in:step:label:onEditingChanged:)
- `LinearGaugeStyle.init(tint: Color)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use ``View/tint(_)`` instead.
- `LinearGaugeStyle.init(tint: Gradient)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use ``View/tint(_)`` instead.
- `BorderedTableStyle.init(alternatesRowBackgrounds: Bool)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the `.bordered` style with the `.alternatingRowBackgrounds()` view modifier
- `PasteButton.init<Payload>(supportedContentTypes: [UTType], validator: @escaping ([NSItemProvider]) -> Payload?, payloadAction: @escaping (Payload) -> Void)` (iOS, macOS, tvOS, watchOS, visionOS)
- `PasteButton.init(supportedTypes: [String], payloadAction: @escaping ([NSItemProvider]) -> Void)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Provide `UTType`s as the `supportedContentTypes` instead.
- `SpatialTapGesture.init(count: Int = 1, coordinateSpace: CoordinateSpace = .local)` (iOS, macOS, tvOS, watchOS, visionOS)
  - use overload that accepts a CoordinateSpaceProtocol instead
- `SwitchToggleStyle.init(tint: Color)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use ``View/tint(_)`` instead.
- `Color.init(_ cgColor: CGColor)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use Color(cgColor:) when converting a CGColor, or create a standard Color directly
- `Color.init(_ color: NSColor)` (macOS)
  - Use Color(nsColor:) when converting a NSColor, or create a standard Color directly

## Functions and Methods

- `View.accessibility(value: Text) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityValue(_:)
- `ModifiedContent.accessibility(value: Text) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityValue(_:)
- `View.actionSheet<T>(item: Binding<T?>, content: (T) -> ActionSheet) -> some View where T : Identifiable` (iOS, macOS, tvOS, watchOS, visionOS)
  - use `confirmationDialog(title:isPresented:titleVisibility:presenting::actions:)`instead.
- `View.actionSheet(isPresented: Binding<Bool>, content: () -> ActionSheet) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - use `confirmationDialog(title:isPresented:titleVisibility:presenting::actions:)`instead.
- `View.alert<Item>(item: Binding<Item?>, content: (Item) -> Alert) -> some View where Item : Identifiable` (iOS, macOS, tvOS, watchOS, visionOS)
  - use `alert(title:isPresented:presenting::actions:) instead.
- `View.alert(isPresented: Binding<Bool>, content: () -> Alert) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - use `alert(title:isPresented:presenting::actions:) instead.
- `View.onContinuousHover(coordinateSpace: CoordinateSpace = .local, perform action: @escaping (HoverPhase) -> Void) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - use overload that accepts a CoordinateSpaceProtocol instead
- `View.listRowPlatterColor(_ color: Color?) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to listItemTint(_:)
- `View.dropDestination<T>(for payloadType: T.Type = T.self, action: @escaping (_ items: [T], _ location: CGPoint) -> Bool, isTargeted: @escaping (Bool) -> Void = { _ in }) -> some View where T : Transferable` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `dropDestination(for:isEnabled:action:)` with an `action` that takes a `DropSession` parameter instead.
- `DropInfo.hasItemsConforming(to types: [String]) -> Bool` (iOS, macOS, tvOS, watchOS, visionOS)
  - Provide `UTType`s as the `types` instead.
- `View.statusBarHidden(_ hidden: Bool = true) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use .toolbarVisibility(_, for: .statusBar) instead
  - Note: `ToolbarPlacement.statusBar` is iOS-only. On visionOS the modifier has no effect (visionOS has no status bar) — remove the call instead of suggesting a replacement.
- `View.statusBar(hidden: Bool) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to statusBarHidden(_:)
- `View.autocapitalization(_ style: UITextAutocapitalizationType) -> some View` (iOS, tvOS, visionOS)
  - use textInputAutocapitalization(_:)
- `ListStyle.static inset(alternatesRowBackgrounds: Bool) -> InsetListStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the `.inset` style with the `.alternatingRowBackgrounds()` view modifier
- `View.navigationBarItems<L, T>(leading: L, trailing: T) -> some View where L : View, T : View` (iOS, macOS, tvOS, visionOS)
  - Use toolbar(_:) with navigationBarLeading or navigationBarTrailing placement
- `View.navigationBarItems<L>(leading: L) -> some View where L : View` (iOS, macOS, tvOS, visionOS)
  - Use toolbar(_:) with navigationBarLeading or navigationBarTrailing placement
- `View.navigationBarItems<T>(trailing: T) -> some View where T : View` (iOS, macOS, tvOS, visionOS)
  - Use toolbar(_:) with navigationBarLeading or navigationBarTrailing placement
- `View.accessibility(hidden: Bool) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityHidden(_:)
- `View.accessibility(label: Text) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityLabel(_:)
- `View.accessibility(hint: Text) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityHint(_:)
- `View.accessibility(inputLabels: [Text]) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityInputLabels(_:)
- `View.accessibility(identifier: String) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityIdentifier(_:)
- `View.accessibility(sortPriority: Double) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilitySortPriority(_:)
- `View.accessibility(activationPoint: CGPoint) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityActivationPoint(_:)
- `View.accessibility(activationPoint: UnitPoint) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityActivationPoint(_:)
- `ModifiedContent.accessibility(hidden: Bool) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityHidden(_:)
- `ModifiedContent.accessibility(label: Text) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityLabel(_:)
- `ModifiedContent.accessibility(hint: Text) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityHint(_:)
- `ModifiedContent.accessibility(inputLabels: [Text]) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityInputLabels(_:)
- `ModifiedContent.accessibility(identifier: String) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityIdentifier(_:)
- `ModifiedContent.accessibility(sortPriority: Double) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilitySortPriority(_:)
- `ModifiedContent.accessibility(activationPoint: CGPoint) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityActivationPoint(_:)
- `ModifiedContent.accessibility(activationPoint: UnitPoint) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityActivationPoint(_:)
- `View.navigationBarHidden(_ hidden: Bool) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use toolbar(.hidden)
- `View.navigationBarTitle(_ title: Text) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to navigationTitle(_:)
- `View.navigationBarTitle(_ titleKey: LocalizedStringKey) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to navigationTitle(_:)
- `View.navigationBarTitle<S>(_ title: S) -> some View where S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to navigationTitle(_:)
- `View.navigationBarTitle(_ title: Text, displayMode: TitleDisplayMode) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use navigationTitle(_:) with navigationBarTitleDisplayMode(_:)
- `View.navigationBarTitle(_ titleKey: LocalizedStringKey, displayMode: TitleDisplayMode) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use navigationTitle(_:) with navigationBarTitleDisplayMode(_:)
- `View.navigationBarTitle<S>(_ title: S, displayMode: TitleDisplayMode) -> some View where S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use navigationTitle(_:) with navigationBarTitleDisplayMode(_:)
- `View.navigationViewStyle<S>(_ style: S) -> some View where S : NavigationViewStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - replace styled NavigationView with NavigationStack or NavigationSplitView instead
- `View.contextMenu<MenuItems>(_ contextMenu: ContextMenu<MenuItems>?) -> some View where MenuItems : View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `contextMenu(menuItems:)` instead.
- `DynamicViewContent.onInsert(of acceptedTypeIdentifiers: [String], perform action: @escaping (Int, [NSItemProvider]) -> Void) -> some DynamicViewContent` (iOS, macOS, tvOS, watchOS, visionOS)
  - Provide `UTType`s as the `supportedContentTypes` instead.
- `View.toolbarBackground(_ visibility: Visibility, for bars: ToolbarPlacement...) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to toolbarBackgroundVisibility(_:for:)
- `View.toolbar(_ visibility: Visibility, for bars: ToolbarPlacement...) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to toolbarVisibility(_:for:)
- `View.onPasteCommand(of supportedTypes: [String], perform payloadAction: @escaping ([NSItemProvider]) -> Void) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Provide `UTType`s as the `supportedContentTypes` instead.
- `View.searchable<S>(text: Binding<String>, placement: SearchFieldPlacement = .automatic, prompt: Text? = nil, @ContentBuilder suggestions: () -> S) -> some View where S : View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the searchable modifier with the searchSuggestions modifier
- `View.searchable<S>(text: Binding<String>, placement: SearchFieldPlacement = .automatic, prompt: LocalizedStringKey, @ContentBuilder suggestions: () -> S) -> some View where S : View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the searchable modifier with the searchSuggestions modifier
- `View.searchable<V, S>(text: Binding<String>, placement: SearchFieldPlacement = .automatic, prompt: S, @ContentBuilder suggestions: () -> V) -> some View where V : View, S : StringProtocol` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the searchable modifier with the searchSuggestions modifier
- `View.tabItem<V>(@ContentBuilder _ label: () -> V) -> some View where V : View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `Tab(title:image:value:content:)` and related initializers instead
- `View.coordinateSpace<T>(name: T) -> some View where T : Hashable` (iOS, macOS, tvOS, watchOS, visionOS)
  - use coordinateSpace(_:) instead
- `View.onLongPressGesture(minimumDuration: Double = 0.5, maximumDistance: CGFloat = 10, pressing: ((Bool) -> Void)? = nil, perform action: @escaping () -> Void) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to onLongPressGesture(minimumDuration:maximumDuration:perform:onPressingChanged:)
- `View.onLongPressGesture(minimumDuration: Double = 0.5, pressing: ((Bool) -> Void)? = nil, perform action: @escaping () -> Void) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to onLongPressGesture(minimumDuration:perform:onPressingChanged:)
- `ListStyle.static bordered(alternatesRowBackgrounds: Bool) -> BorderedListStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the `.bordered` style with the `.alternatingRowBackgrounds()` view modifier
- `TabViewCustomization.resetSectionOrder(for sectionID: String)` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the `section` subscript and call `resetTabOrder` instead.
- `View.disableAutocorrection(_ disable: Bool?) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to autocorrectionDisabled(_:)
- `View.menuButtonStyle<S>(_ style: S) -> some View where S : MenuButtonStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `menuStyle(_:)` instead.
- `View.accessibility(addTraits traits: AccessibilityTraits) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityAddTraits(_:)
- `View.accessibility(removeTraits traits: AccessibilityTraits) -> ModifiedContent<Self, AccessibilityAttachmentModifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityRemoveTraits(_:)
- `ModifiedContent.accessibility(addTraits traits: AccessibilityTraits) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityAddTraits(_:)
- `ModifiedContent.accessibility(removeTraits traits: AccessibilityTraits) -> ModifiedContent<Content, Modifier>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to accessibilityRemoveTraits(_:)
- `View.onTapGesture(count: Int = 1, coordinateSpace: CoordinateSpace = .local, perform action: @escaping (CGPoint) -> Void) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - use overload that accepts a CoordinateSpaceProtocol instead
- `View.foregroundColor(_ color: Color?) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to foregroundStyle(_:)
- `View.accentColor(_ accentColor: Color?) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the asset catalog's accent color or View.tint(_:) instead.
- `View.overlay<Overlay>(_ overlay: Overlay, alignment: Alignment = .center) -> some View where Overlay : View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `overlay(alignment:content:)` instead.
- `View.mask<Mask>(_ mask: Mask) -> some View where Mask : View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use overload where mask accepts a @ContentBuilder instead.
- `GeometryProxy.frame(in coordinateSpace: CoordinateSpace) -> CGRect` (iOS, macOS, tvOS, watchOS, visionOS)
  - use overload that accepts a CoordinateSpaceProtocol instead
- `Font.static system(_ style: TextStyle, design: Design = .default) -> Font` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `system(_:design:weight:)` instead.
- `Text.foregroundColor(_ color: Color?) -> Text` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to foregroundStyle(_:)
- `View.background<Background>(_ background: Background, alignment: Alignment = .center) -> some View where Background : View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `background(alignment:content:)` instead.
- `View.edgesIgnoringSafeArea(_ edges: Set) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use ignoresSafeArea(_:edges:) instead.
- `View.cornerRadius(_ radius: CGFloat, antialiased: Bool = true) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `clipShape` or `fill` instead.
- `Font.static system(size: CGFloat, weight: Weight = .regular, design: Design = .default) -> Font` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `system(size:weight:design:)` instead.
- `View.colorScheme(_ colorScheme: ColorScheme) -> some View` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to preferredColorScheme(_:)
- `Section.collapsible(_ collapsible: Bool) -> some View` (macOS, tvOS, watchOS)
  - Use a standard Section initializer which does not allow for collapsibility\nby default after macOS 14.0.

## Properties

- `NavigationViewStyle.static columns: ColumnNavigationViewStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - replace styled NavigationView with NavigationSplitView
- `ToolbarItemPlacement.static navigationBarLeading: ToolbarItemPlacement` (iOS, macOS, tvOS, watchOS, visionOS)
  - use topBarLeading instead
- `ToolbarItemPlacement.static navigationBarTrailing: ToolbarItemPlacement` (iOS, macOS, tvOS, watchOS, visionOS)
  - use topBarTrailing instead
- `EnvironmentValues.presentationMode: Binding<PresentationMode>` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use isPresented or dismiss
- `NavigationViewStyle.static automatic: DefaultNavigationViewStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - replace styled NavigationView with NavigationStack or NavigationSplitView instead
- `MenuStyle.static borderlessButton: BorderlessButtonMenuStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use .menuStyle(.button) and .buttonStyle(.borderless).
- `EnvironmentValues.disableAutocorrection: Bool?` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to autocorrectionDisabled
- `NavigationViewStyle.static stack: StackNavigationViewStyle` (iOS, macOS, tvOS, watchOS, visionOS)
  - replace stack-styled NavigationView with NavigationStack
- `EnvironmentValues.sizeCategory: ContentSizeCategory` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to dynamicTypeSize
- `Color.cgColor: CGColor?` (iOS, macOS, tvOS, watchOS, visionOS)
  - Renamed to resolve(in:)
- `EnvironmentValues.controlActiveState: ControlActiveState` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use `EnvironmentValues.appearsActive` instead.
- `SurroundingsEffect.static systemDark: SurroundingsEffect` (macOS, visionOS)
  - Renamed to dark

## Subscripts

- `TabViewCustomization.subscript(sectionID id: String) -> [String]?` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the `section` subscript and read `tabOrder` instead.
- `TabViewCustomization.subscript(sidebarVisibility id: String) -> Visibility` (iOS, macOS, tvOS, watchOS, visionOS)
  - Use the `tab` subscript and read `sidebarVisibility` instead.

# Soft-Deprecated APIs

SwiftUI has a number of APIs that are "soft deprecated." A soft-deprecated API is marked deprecated in the SDK headers, but with a deprecation version of `100000.0` — a placeholder that suppresses compiler warnings while signaling that the API should no longer be used in new code.

## Scoping rule — read this first

All soft-deprecation guidance in this document is scoped to the code you are directly modifying. If a file contains multiple views and the user's task only involves one of them, the other views are out of scope.

**What to do**: Only discuss the view(s) you edited. Structure your response as: code output, then reasoning about *your changes*. Nothing else.

**What not to do**: Do not mention, flag, comment on, offer to migrate, or ask about soft-deprecated APIs in out-of-scope code. This includes trailing questions like "Would you like me to migrate OtherView to NavigationStack?" — if you didn't edit that view, don't bring it up. The scoping rule takes precedence over any prompt asking for "observations" or "other notes."

**Why**: Mentioning soft-deprecated APIs in code the user did not ask you to change creates noise, distracts from the task, and pressures the user to do unrelated work.

**Example of what NOT to do**: The user asks you to add a button to `SettingsView`. The same file contains `DashboardView` which uses `NavigationView`. Do not write anything like "I noticed DashboardView uses NavigationView, which is soft-deprecated" or "Note on DashboardView: NavigationView is soft-deprecated." Do not mention `DashboardView` at all.

## How to identify soft-deprecated APIs

Check `references/soft-deprecated-apis.md` for a comprehensive list of all known soft-deprecated SwiftUI APIs and their replacements. The file header shows which SDK versions it was generated from.

If you are working with a newer SDK than the versions listed, this list may be incomplete. In that case, also check the `@available` attribute in the SDK headers. A soft-deprecated API has `deprecated: 100000.0`.

## When generating code

Never recommend or generate code that uses a soft-deprecated API. If you are not certain that an API is not soft-deprecated, check the list in `references/soft-deprecated-apis.md` before recommending it. Any API — even one that worked in a prior release — could have been soft-deprecated since then. Do not rely on memory; verify against the list.

## When the user asks to review, refactor, modernize, or clean up code

Point out soft-deprecated APIs in the code the user asked you to review and suggest the modern replacement. Treat this as informational, not urgent — soft-deprecated APIs still compile and work.

## When the user asks to add a feature or fix a bug

If the view you are editing uses a soft-deprecated API, do NOT replace it in your code output. Keep the existing API exactly as it was, and after providing the requested change, add a brief note offering to migrate as a separate step.

If a *different* view in the same file uses a soft-deprecated API, ignore it completely. Do not mention it, do not offer to migrate it, do not ask about it. You are only responsible for the view you were asked to edit.

**Example — view you ARE editing**: The user asks you to add a search bar to a view that uses `NavigationView`. Your code output must still use `NavigationView`. After the code block, write something like: "I noticed this view uses `NavigationView`, which is soft-deprecated. Would you like me to migrate it to `NavigationSplitView` while I'm in this code?"

**Example — view you are NOT editing**: The user asks you to add a search bar to `SearchView`. The same file contains `HomeView` which uses `NavigationView`. Say nothing about `HomeView` or its use of `NavigationView`. Do not write "I also noticed HomeView uses NavigationView." Do not ask "Would you like me to migrate HomeView?"

**Why**: The user asked for a feature, not a refactor. Silently changing APIs they didn't ask about creates unexpected diffs, risks regressions, and makes the change harder to review. Commenting on views they didn't ask about creates noise and pressure to do unrelated work.

## General guidance

- Never introduce new usages of soft-deprecated APIs in code you write from scratch.
- Don't proactively search for or scan for soft-deprecated APIs — only notice them when they appear in code you are directly modifying for the user's request.

# View Structure

A view is SwiftUI's unit of invalidation. When something changes, SwiftUI re-runs the body of the smallest enclosing view that depends on what changed. Factoring affects performance (not just readability), and `init` runs much more often than people expect. For what data each view should take as input and how that affects invalidation, see `dataflow.md`.

When building a new view with distinct sections — a header, a list, a footer, sidebar + main, content + counter, or any multi-region layout — declare each section as its own `struct` conforming to `View`. Do **not** factor sections as `private var` computed properties or `@ViewBuilder` helper methods on the parent. The sections below explain why and show the AVOID/PREFER patterns.

## Always use separate `View` types for sections, not computed properties

Long `var body` implementations are hard to read, but the more important problem is that everything inside the same body is part of the same invalidation boundary. When any input to a view changes, SwiftUI re-evaluates the entire body — every conditional, every modifier chain, every string interpolation — even if only one small leaf actually depends on what changed.

Factor large bodies into individual `View` types, not into computed properties or `@ViewBuilder` helper functions. A computed property is inlined into the enclosing view's body; it does not introduce its own invalidation boundary, so it does not reduce update cost. A separate `View` type with explicit, narrow inputs invalidates only when those inputs change.

```swift
// AVOID: Computed properties look like factoring but share the parent's
// invalidation boundary. Toggling `isExpanded` invalidates `ProfileView`,
// which re-evaluates `header`, `details`, AND `footer` together — even
// though only `details` actually reads `isExpanded`.
struct ProfileView: View {
    @State private var isExpanded = false
    let user: User
    let stats: Stats

    var body: some View {
        VStack {
            header
            details
            footer
        }
    }

    private var header: some View {
        HStack {
            Image(systemName: "person.circle")
            Text(user.name).font(.title)
        }
    }

    private var details: some View {
        Group {
            if isExpanded {
                Text(user.bio)
                Text(user.location)
            }
        }
    }

    private var footer: some View {
        HStack {
            Label("\(stats.followers)", systemImage: "person.2")
            Label("\(stats.posts)", systemImage: "doc.text")
        }
        .font(.caption)
    }
}
```

```swift
// PREFER: Each subview is its own invalidation boundary with its own
// inputs. Toggling `isExpanded` invalidates `ProfileView` and
// `ProfileDetails`; `ProfileHeader` and `ProfileFooter` are skipped
// because none of their inputs changed.
struct ProfileView: View {
    @State private var isExpanded = false
    let user: User
    let stats: Stats

    var body: some View {
        VStack {
            ProfileHeader(name: user.name)
            ProfileDetails(
                bio: user.bio,
                location: user.location,
                isExpanded: isExpanded
            )
            ProfileFooter(followers: stats.followers, posts: stats.posts)
            Button(isExpanded ? "Less" : "More") { isExpanded.toggle() }
        }
    }
}

struct ProfileHeader: View {
    let name: String

    var body: some View {
        HStack {
            Image(systemName: "person.circle")
            Text(name).font(.title)
        }
    }
}

struct ProfileDetails: View {
    let bio: String
    let location: String
    let isExpanded: Bool

    var body: some View {
        if isExpanded {
            Text(bio)
            Text(location)
        }
    }
}

struct ProfileFooter: View {
    let followers: Int
    let posts: Int

    var body: some View {
        HStack {
            Label("\(followers)", systemImage: "person.2")
            Label("\(posts)", systemImage: "doc.text")
        }
        .font(.caption)
    }
}
```

Pass each subview only the data it actually uses — the same rule as "Pass views only the data they read" in `dataflow.md`. The example above already follows it: each subview takes exactly the fields it reads, not the parent's full `User`/`Stats` structs.

Computed properties and small `@ViewBuilder` helpers still have a place for tiny fragments reused two or three times within the same body that have no independent invalidation story. The rule targets factoring done for *organization* or to manage *body length*, where a real `View` type does the right thing.

### Multi-section detail views

The most common write-from-requirements case where this rule gets dropped: a prompt asks for a `SomethingDetailView` with multiple distinct sections — header + body + metadata + related items, header + ingredients + steps + footer, hero + description + specs + reviews, etc. The training-data shape for this prompt is "single `View` with `private var header: some View`, `private var body: some View`, etc." That shape is wrong. Always factor each named section as a separate `View` type with narrow inputs.

```swift
// PREFER: Detail view with multiple sections, each section a separate
// `View` type that takes only the fields it renders. The parent stays
// thin — it just composes the sections.
struct ProductDetailView: View {
    let product: Product

    var body: some View {
        ScrollView {
            VStack(alignment: .leading, spacing: 24) {
                ProductHeader(name: product.name, price: product.price)
                ProductGallery(images: product.imageURLs)
                ProductDescription(text: product.descriptionText)
                ProductReviews(
                    averageStars: product.averageStars,
                    reviewCount: product.reviewCount
                )
            }
            .padding()
        }
    }
}

struct ProductHeader: View {
    let name: String
    let price: Decimal

    var body: some View {
        VStack(alignment: .leading, spacing: 4) {
            Text(name).font(.largeTitle).fontWeight(.bold)
            Text(price, format: .currency(code: "USD"))
                .font(.title2)
                .foregroundStyle(.secondary)
        }
    }
}

struct ProductGallery: View {
    let images: [URL]

    var body: some View {
        ScrollView(.horizontal) {
            HStack {
                ForEach(images, id: \.self) { url in
                    AsyncImage(url: url) { image in
                        image.resizable().scaledToFill()
                    } placeholder: {
                        Color.secondary.opacity(0.2)
                    }
                    .frame(width: 120, height: 120)
                    .clipShape(RoundedRectangle(cornerRadius: 12))
                }
            }
        }
    }
}

struct ProductDescription: View {
    let text: String

    var body: some View {
        Text(text).font(.body)
    }
}

struct ProductReviews: View {
    let averageStars: Double
    let reviewCount: Int

    var body: some View {
        HStack {
            Label("\(averageStars, specifier: "%.1f")", systemImage: "star.fill")
            Text("(\(reviewCount) reviews)")
                .foregroundStyle(.secondary)
        }
        .font(.subheadline)
    }
}
```

This shape generalizes to every other detail view: `MovieDetailView`, `RecipeDetailView`, `ArticleDetailView`, `ProfileDetailView`, `EpisodeDetailView`. Same factoring every time — one `View` type per section, narrow inputs each, thin parent that composes them. Don't reach for `private var header: some View` on the parent.

## Keep view `init` cheap

A view's `init` runs every time the parent re-evaluates its body, which can be many times per second for views inside `List`, `LazyVStack`, scroll containers, or animated parents. Treat `init` as a constant-time copy of inputs into stored properties. Don't load data, decode JSON, touch the file system, format dates, or allocate large structures there.

```swift
// AVOID: Expensive work in `init`. Every time the parent's body runs,
// the JSON is decoded again, the date formatter is allocated again,
// and the formatted string is rebuilt — even though the inputs haven't
// changed.
struct WeatherCard: View {
    let summary: WeatherSummary
    let formattedDate: String

    init(rawJSON: Data, date: Date) {
        self.summary = try! JSONDecoder().decode(WeatherSummary.self, from: rawJSON)
        let formatter = DateFormatter()
        formatter.dateStyle = .medium
        self.formattedDate = formatter.string(from: date)
    }

    var body: some View {
        VStack {
            Text(summary.headline)
            Text(formattedDate)
        }
    }
}
```

```swift
// PREFER: Inputs are already-prepared values. Decoding lives in the
// model layer (or in a `.task`); formatting uses SwiftUI's built-in
// `Text(_:format:)` which is cached and locale-aware.
struct WeatherCard: View {
    let summary: WeatherSummary
    let date: Date

    var body: some View {
        VStack {
            Text(summary.headline)
            Text(date, format: .dateTime.day().month().year())
        }
    }
}
```

If a derived value really does need to be computed once and cached for the view's lifetime, store it on an `@State`-owned `@Observable` model or compute it asynchronously in `.task`. `init` is not a one-time setup hook; it runs as often as the parent's body does.

## Single Child `Group`

`Group { SomeView() }`, which is a `Group` with only one child, isn't free. Even though it has no visual effect, it wraps the view in an additional type, `Group<SomeView>`. Every modifier you chain after it (`.onChange`, `.background`, `.frame`, etc.) has to be type-checked against that wrapped type instead of the underlying view's type. In long modifier chains this extra type wrapper can add totally unnecessary type checking overhead.

The "single child" rule is specifically about *one concrete view*. A `Group` whose content is a `ForEach`, a `TupleView` of sibling views, or an `if`/`else` (which produces `_ConditionalContent`) is doing real work and is fine.

```swift
// AVOID: A single concrete child inside Group. The Group wraps `Text` in
// an extra type that every chained modifier must type-check against, for
// no behavioral benefit.
Group {
    Text(status)
}
.padding(.horizontal, 8)
.background(.thinMaterial, in: Capsule())
```

```swift
// PREFER: Drop the Group and chain the modifiers directly on the child.
Text(status)
    .padding(.horizontal, 8)
    .background(.thinMaterial, in: Capsule())
```

```swift
// PREFER: Multiple siblings is exactly what Group is for — modifiers
// apply to each child as a unit without needing an HStack/VStack
// container that would change layout.
Group {
    Button("Save", action: onSave)
    Button("Cancel", action: onCancel)
    Button("Delete", role: .destructive, action: onDelete)
}
.buttonStyle(.borderedProminent)
.controlSize(.large)
```

```swift
// PREFER: Wrapping an `if`/`else` in Group so a shared modifier applies
// uniformly to both branches. This is NOT the single-child anti-pattern —
// the Group's content is `_ConditionalContent<...>`, not a single concrete
// view, and removing the Group would either drop the modifier from one
// branch or force you to repeat it on both.
Group {
    if let label {
        Text(label)
            .padding(4)
            .background(.thinMaterial, in: Capsule())
    } else {
        Color.clear
    }
}
.accessibilityHidden(label == nil)
```