Swift Property Wrapper Attribute

A property wrapper is a compiler-synthesized mechanism that introduces a layer of separation between the code that manages how a property is stored and the code that defines the property. By applying the @propertyWrapper attribute to a custom type, you define a reusable encapsulation strategy for property access and mutation. To create a property wrapper, a struct, class, or enum must be annotated with the @propertyWrapper attribute and must implement a non-static property named wrappedValue.

@propertyWrapper
struct CustomWrapper<Value> {
    private var storage: Value
    
    init(wrappedValue: Value) {
        self.storage = wrappedValue
    }
    
    var wrappedValue: Value {
        get { return storage }
        set { storage = newValue }
    }
}

Compiler Desugaring

When you apply a property wrapper to a declaration, the Swift compiler automatically generates a backing storage variable and routes all access to the original property through the wrapper’s wrappedValue.

struct Model {
    @CustomWrapper var data: Int = 0
}

Under the hood, when applied to a property on a type, the compiler desugars the declaration into the following equivalent code:

struct Model {
    // 1. Private backing storage initialized with the wrapper type
    private var _data: CustomWrapper<Int> = CustomWrapper<Int>(wrappedValue: 0)

    // 2. Computed property exposing the wrappedValue
    var data: Int {
        get { return _data.wrappedValue }
        set { _data.wrappedValue = newValue }
    }
}

When a property wrapper is applied to a local variable within a function, the compiler synthesizes the same backing storage and computed access, but access control modifiers (like private) are omitted since they do not apply to local scopes.

Initialization Semantics

Property wrappers support implicit initialization at the call site if the wrapper type defines an init(wrappedValue:) initializer. When a default value is assigned to the wrapped property, the compiler translates this assignment into a call to this specific initializer.

@propertyWrapper
struct InitializableWrapper<Value> {
    var wrappedValue: Value
    
    init(wrappedValue: Value) {
        self.wrappedValue = wrappedValue
    }
}

struct InitializationModel {
    // The compiler translates this to: 
    // private var _count = InitializableWrapper(wrappedValue: 10)
    @InitializableWrapper var count: Int = 10
}

Wrappers can also define custom initializers to accept additional arguments. These are passed in the attribute declaration syntax.

@propertyWrapper
struct ConfiguredWrapper<Value> {
    var wrappedValue: Value
    
    init(wrappedValue: Value, configuration: String) {
        self.wrappedValue = wrappedValue
    }
}

struct ConfiguredModel {
    @ConfiguredWrapper(configuration: "strict") var count: Int = 10
}

Projected Values

A property wrapper can optionally expose a secondary API by defining a projectedValue property. The compiler synthesizes access to this projected value by prefixing the original property name with a dollar sign ($). The projectedValue can return any type, including self (the wrapper instance itself), allowing external code to interact with the wrapper’s internal state or auxiliary methods.

@propertyWrapper
struct ProjectedWrapper<Value> {
    var wrappedValue: Value
    
    var projectedValue: ProjectedWrapper<Value> {
        return self
    }
    
    func auxiliaryMethod() { }
}

struct ProjectedModel {
    @ProjectedWrapper var data: Int = 0
    
    func accessProjection() {
        let value: Int = data                           // Accesses wrappedValue
        let wrapper: ProjectedWrapper<Int> = $data      // Accesses projectedValue
        
        $data.auxiliaryMethod()
    }
}

Architectural Constraints

Protocols: Property wrappers cannot be applied to property requirements inside a protocol declaration (e.g., protocol P { @Wrapper var x: Int { get } } is invalid).
Property Modifiers: A property wrapper cannot be applied to lazy, weak, unowned, or computed properties.
Access Control:
- Backing Storage: When applied to a type’s property, the synthesized backing storage (_propertyName) is always private. When applied to a local variable, access control modifiers do not apply.
- Wrapped and Projected Values: The synthesized properties (propertyName and $propertyName) share the access level of the original property declaration. Consequently, the wrapper’s underlying wrappedValue and projectedValue implementations must be at least as accessible as the wrapped property. If a property is declared public but the wrapper’s projectedValue is internal, the compiler does not silently downgrade the projection’s access level; instead, it emits a compile-time error.

Tired of Poor Swift Skills? Fix That With Deep Grasping!Learn More

Methods

Initializers

Closures

Type Declarations

Properties

Generics

Optional Binding

Patterns

Extensions

Error Handling

Attributes

Subscripts

Parameters

Constants & Variables

Conditionals

Loops

Collection Types

Basic Types

Numeric Types

Imports

Comments

Optional Operators

Arithmetic Operators

Overflow Operators

Assignment Operators

Bitwise Operators

Comparison Operators

Conditional Operators

Logical Operators

Range Operators

Type-Casting Operators

Swift Property Wrapper Attribute

Compiler Desugaring

Initialization Semantics

Projected Values

Architectural Constraints

​Compiler Desugaring

​Initialization Semantics

​Projected Values

​Architectural Constraints

Compiler Desugaring

Initialization Semantics

Projected Values

Architectural Constraints