> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ```swift theme={"dark"} @propertyWrapper struct CustomWrapper { 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`. ```swift theme={"dark"} 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: ```swift theme={"dark"} struct Model { // 1. Private backing storage initialized with the wrapper type private var _data: CustomWrapper = CustomWrapper(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. ```swift theme={"dark"} @propertyWrapper struct InitializableWrapper { 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. ```swift theme={"dark"} @propertyWrapper struct ConfiguredWrapper { 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. ```swift theme={"dark"} @propertyWrapper struct ProjectedWrapper { var wrappedValue: Value var projectedValue: ProjectedWrapper { return self } func auxiliaryMethod() { } } struct ProjectedModel { @ProjectedWrapper var data: Int = 0 func accessProjection() { let value: Int = data // Accesses wrappedValue let wrapper: ProjectedWrapper = $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