Property wrappers

The problem it solves

Every codebase accumulates properties that need the same ceremony around every access. A settings screen, before wrappers:

final class Settings {
    var volume: Int {
        get { readFromDisk("volume") ?? 5 }
        set { writeToDisk("volume", min(10, max(0, newValue))) }
    }
    var brightness: Int {
        get { readFromDisk("brightness") ?? 7 }
        set { writeToDisk("brightness", min(10, max(0, newValue))) }
    }
    // …and eight more, identical except for the key.
}

The clamping logic and the disk round-trip are duplicated per property, and every new setting is a chance to copy the pattern slightly wrong. This shape — per-property behaviour that is identical across many properties — is exactly what property wrappers exist for. In real projects you meet it constantly: values that must be clamped, strings that must be trimmed, settings that must persist, fields that must be validated, access that must be logged.

What a wrapper is

A property wrapper is a type marked @propertyWrapper with one requirement: a property named wrappedValue.

@propertyWrapper
struct Clamped {
    private var value: Int
    let range: ClosedRange<Int>

    var wrappedValue: Int {
        get { value }
        set { value = min(range.upperBound, max(range.lowerBound, newValue)) }
    }

    init(wrappedValue: Int, _ range: ClosedRange<Int>) {
        self.range = range
        self.value = min(range.upperBound, max(range.lowerBound, wrappedValue))
    }
}

Using it deletes the duplication:

struct AudioSettings {
    @Clamped(0...10) var volume = 5
    @Clamped(0...10) var brightness = 7
}

Every read and write of volume now goes through Clamped.wrappedValue. The rule lives in one place; ten properties share it.

What the compiler actually generates

This is the part worth genuinely understanding, because it explains every _ and $ you will ever see in SwiftUI. For @Clamped(0...10) var volume = 5, the compiler writes, mechanically:

private var _volume = Clamped(wrappedValue: 5, 0...10)   // the storage

var volume: Int {                                        // the façade
    get { _volume.wrappedValue }
    set { _volume.wrappedValue = newValue }
}

That is the whole feature. @Wrapper var x is sugar for a hidden stored property _x of the wrapper type, plus a computed x that passes through it. No runtime magic — a source transformation you could do by hand.

And because the runtime in this page has no macro expansion, doing it by hand is exactly how we will run it — which has the nice side effect of proving there is nothing else hiding in there:

In Xcode you write the two-line sugared version; the behaviour is identical to this expansion.

$ — the projected value

A wrapper can expose a second interface by declaring projectedValue. Whatever type that property returns is what $name gives you.

@propertyWrapper
struct Logged {
    private var value: Int
    private(set) var projectedValue: [String] = []   // $property → the history

    var wrappedValue: Int {
        get { value }
        set {
            projectedValue.append("\(value) → \(newValue)")
            value = newValue
        }
    }

    init(wrappedValue: Int) { self.value = wrappedValue }
}

Now the two prefixes make a complete picture:

This is precisely why $searchText in SwiftUI is a Binding<String>: State.projectedValue is declared as Binding<Value>. Nothing about $ is specific to bindings — @Published's projection is a Combine publisher, and yours can be anything useful.

The wrappers you already use

Now every SwiftUI attribute you have met is readable as ordinary code:

@AppStorage is worth pausing on, because it is the disk-backed settings problem from the top of this lesson, solved by Apple with this exact feature: @AppStorage("volume") var volume = 5 reads and writes UserDefaults on every access, and projects a binding so a Slider can edit it directly. The ceremony you would have written per-property lives once, inside the wrapper.