Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 46 ยท State and Data Flow

Choosing the Right Property Wrapper

A decision guide for @State, @Binding, @Bindable, @Environment, @AppStorage and @SceneStorage, with the single-source-of-truth rule and the mistakes to avoid.

SwiftUI gives you six or seven ways to hold data in a view, and they look similar on the page. Beginners often pick one at random, see the screen misbehave, and swap to another until it works. That approach leaves hidden bugs: a counter that resets, a text field that edits a copy, a setting that is forgotten after a relaunch.

There is a better way. Instead of asking "which wrapper do I like?", ask three questions about each piece of data: who owns it, how long must it live, and who else needs to change it? The answers point to exactly one wrapper. This lesson turns those questions into a decision guide. It builds on @State and @Binding and @Observable and Observation, so read those first if the names are new.

One piece of data, one owner

Owner Exactly one place creates and stores the value.
Borrowers Everyone else gets a link, never a copy.
Updates The UI is rebuilt from the one true value.

This is the single source of truth.

1 / 2

The single source of truth

Every piece of state should be stored in exactly one place. Everything else that shows or edits it must refer to that place. If two views each keep their own copy of "is the switch on?", they will disagree the moment one of them changes.

Value types such as Bool, Int and structs are copied when you pass them around. That is usually what you want in Swift, but for UI state it is the classic trap. The fix is a binding: a pair of "read" and "write" closures that point back to the owner's storage. The stand-in below shows the problem and the fix with a small Binding of our own (the real one is generic in the same way).

Swift A copy diverges, a binding stays in sync

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

The copy flipped to true while the owner still said false. The linked version changed the owner itself, so every other view reading owner.value would see the change. In SwiftUI the parent writes ChildView(isOn: $isOn), where $isOn is the projected Binding<Bool>, and the child declares @Binding var isOn: Bool.

The decision guide

Walk through the questions in order and stop at the first "yes".

  1. Does this view create and own the data, and is it only needed for as long as the view exists? Use @State. Mark it private, because nobody else should assign it.
  2. Does a parent own the data and this view needs to read and write it? Use @Binding. The child never creates the value.
  3. Is the data an @Observable class created by this view? Use @State too: @State private var model = ShoppingModel() keeps one instance alive across redraws.
  4. Did a parent hand over an @Observable object, and you need $model.name bindings to its properties? Use @Bindable.
  5. Does the data come from far above in the tree, and passing it through every level would be noisy? Use @Environment.
  6. Must the value survive quitting the app, such as a theme or a "seen the intro" flag? Use @AppStorage.
  7. Must a window restore its own small UI state, such as the selected tab or a scroll position? Use @SceneStorage.
  8. Does the view only read a value that the parent passes in? Use a plain let or var property. No wrapper at all.

That last case is the most overlooked. A view that merely displays a title does not need any property wrapper.

Swift
struct RatingRow: View {
    let title: String          // plain value, read only
    @Binding var stars: Int    // owned by the parent, edited here

    var body: some View {
        Stepper("\(title): \(stars)", value: $stars, in: 0...5)
    }
}

Notice that the parent decides who owns stars; RatingRow just borrows it. The same RatingRow can then edit a @State value, a property of an @Observable model or a constant in a preview.

Each wrapper in one paragraph

@State stores a value (or a reference to an @Observable object) that SwiftUI keeps alive for the view's identity, even though the view struct itself is recreated many times. Declare it private and give it an initial value. Mutating it invalidates the view.

@Binding is a reference to someone else's state. It has no storage of its own. You pass it with the $ prefix and read or write it through wrappedValue, just like a normal property.

@Bindable is for @Observable classes. An observable object's properties are not bindings by themselves, so TextField("Name", text: $model.name) needs @Bindable var model first. It does not own the object; it only unlocks the $ syntax.

@Environment reads a value that an ancestor injected, such as the color scheme or your own settings object. You will build custom ones in the next lesson.

@AppStorage reads and writes a UserDefaults key and invalidates the view when the key changes. It suits small preferences: Bool, Int, Double, String, URL, Data, and enums whose raw value is an Int or String.

@SceneStorage is similar but stores state per scene (per window) and is meant for restoring where the user was after the system relaunches the app. It is for small values, not for data.

Neither @AppStorage nor @SceneStorage is a place for secrets or large data. Passwords and tokens belong in the Keychain, and real records belong in a database; both are covered in the persistence chapter.

A chooser you can run

The decision list is mechanical enough to write as code. The stand-in below encodes the questions as a small struct and prints the recommendation for several pieces of data in a settings screen. Real SwiftUI cannot run here, but the reasoning is the same.

Swift A property wrapper chooser

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readLine()), it gets the next line from this box.

Try changing lifetime on the first fact to .acrossLaunches and run it again; the answer moves from @State to @AppStorage. Lifetime, not taste, picks the wrapper.

Common mistakes

Making a child own what the parent owns. If a child declares @State var isOn = false and the parent also keeps isOn, you have two sources of truth. Replace the child's version with @Binding.

Initializing @State from a parameter and expecting updates. @State takes its initial value once, when the view's identity first appears. If the parent later passes a different value, the child ignores it. Use a let property for read-only input or a @Binding for two-way input.

Using @State for an object that is not observable. A plain class stored in @State will survive redraws, but changing its properties does not refresh the screen. Mark the class @Observable.

Forgetting private on @State. If it is not private, a parent can pass an initial value in its initializer, which blurs ownership and surprises readers.

Using @AppStorage for everything. It writes to disk-backed UserDefaults and every view that reads the key refreshes on change. Reserve it for real preferences; keep transient screen state in @State.

Storing derived values. If total can be computed from items, make it a computed property, not a second @State. A stored copy will go stale.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A parent view owns a Bool and a child view needs to flip it. What should the child declare?

    A binding is a read/write link to the parent's storage. A @State in the child would be a second copy, and a plain let cannot write.
  2. 2. Which wrapper is used to get $model.name bindings for an @Observable object that a parent passed in?

    @Bindable unlocks the $ syntax for the properties of an observable object. It does not own the object.
  3. 3. A setting must still be there after the user force-quits and relaunches the app. Which fits best?

    @AppStorage is backed by UserDefaults, so it persists across launches. @State is lost when the view goes away.
  4. 4. A view only displays a title string that its parent passes in. What does it need?

    Read-only input needs no wrapper. Extra wrappers suggest ownership or write access the view does not have.
  5. 5. Why is it risky for two views to each keep their own @State for the same value?

    Each copy changes independently. Keep one owner and give the others a binding.

Summary

  • Ask who owns the data, how long it must live and who needs to change it; the answers pick the wrapper.
  • Keep one source of truth. Share it with @Binding (or @Bindable for observable objects), never by copying.
  • @State is for data a view creates and owns for its own lifetime, and should be private.
  • @Environment injects shared values from above; @AppStorage persists preferences; @SceneStorage restores per-window UI state.
  • Read-only input needs no wrapper, and derived values should be computed, not stored.

Next, learn how the environment carries shared values and services down the tree in The Environment and Dependency Injection.