NEW: Start my new Ultimate Portfolio App course with a free Hacking with Swift+ trial! >>

< Back to Latest Articles

Creating a custom property wrapper using DynamicProperty

It’s not hard to make a basic property wrapper, but if you want one that automatically updates the body property like @State you need to do some extra work. In this article I’ll show you exactly how it’s done, as we build a property wrapper capable of reading and writing documents from our app’s container.

Watch the video here, or read the article below

Reading and writing

We’re going to approach this property wrapper in two passes: a first pass able to read and write values, and a second pass that’s able to project a binding as well.

First, the easy part: we’re going to create a new property wrapper struct called Document that will store its value as a string, and also a URL pointing to the file it’s modifying. Because we’ll want to modify the text value over time, we’ll mark with the @State property wrapper so SwiftUI will look after it for us.

Start with this:

@propertyWrapper struct Document {
    @State private var value = ""
    private let url: URL

In order to be a valid property wrapper, our Document struct needs to have a wrappedValue property that stores the actual value we’re working with. In our case we already have that in value, but we made that private for a reason: when we interact with this property wrapper we want to add some extra work so that our new value gets written to disk automatically.

So, our wrappedValue property will be computed: when we’re reading it we’ll just send back value, but when we’re writing we’ll save it to wherever our file URL is then update value.

Now, we need a little bit of SwiftUI magic here, because if we have a setter for wrappedValue then we’ll be modifying the struct we’re inside and that will cause problems. Fortunately, we’re not actually changing the Document struct: we’re using @State, so we’re bypassing the struct entirely and having SwiftUI store the value. So, rather than making a regular setter, we can instead make a nonmutating setter, because our underlying struct won’t actually be changing.

Add this property to Document now:

var wrappedValue: String {
    get {
    nonmutating set {
        do {
            try newValue.write(to: url, atomically: true, encoding: .utf8)
            value = newValue
        } catch {
            print("Failed to write output")

And now we just need an initializer that provides initial values for both url and the value state. The first of these we can figure out by using FileManager to append the user’s filename to the app’s documents directory, but for the latter we need to load the initial value of the text file and wrap that in a State object.

Here’s that in code:

init(_ filename: String) {
    let paths = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)
    url = paths[0].appendingPathComponent(filename)

    let initialText = (try? String(contentsOf: url)) ?? ""
    _value = State(wrappedValue: initialText)

That’s it – that’s our first pass of the property wrapper complete. To try it we need to update ContentView to use the @Document property wrapper and place its context inside a text view, but in order to make the test interesting we’re also going to add a button to simulate changing its value – this will just generate a random number and place it into the document.

Here’s the new ContentView:

struct ContentView: View {
    @Document("test.txt") var document

    var body: some View {
        NavigationView {
            VStack {

                Button("Change document") {
                    document = String(Int.random(in: 1...1000))

If you run that now you’ll see the text view is empty by default, and if you press the button nothing will happen. Yes, after all that work we don’t actually have much to show, but that’s okay: with one tiny change we can bring the whole thing to life.

You see, right now SwiftUI doesn’t realize it should be watching our property wrapper for change notification, even though it has an @State property inside there. To fix this we need to make Document conform to the DynamicProperty protocol, like this:

@propertyWrapper struct Document: DynamicProperty {

In fact, that’s all we need to do – SwiftUI will take care of the rest for us. Go ahead and run the app again, because if you press the button it will update automatically. Even better, the new contents have been written to “test.txt” automatically, so if you relaunch the app you’ll see it remembers its last value – nice!

Projecting values

Wrapping a simple string works great for simple property wrappers like we have right now, but for more advanced purposes you’re also likely to want to expose a projected value. This allows us to create an alternative way of using the property we’re wrapping, and it’s down to us to define exactly what it does.

SwiftUI’s own @State property wrapper uses the projected value to create a binding for its data, and if we do the same thing here then it would allow us to bind directly to a document so that every change we make gets saved out.

This takes remarkably little code to accomplish. First we need to add a new property to Document that declares our projected value and how it works. Projected values must always be called projectedValue, but otherwise can work however you want.

So, start by adding this property to Document:

var projectedValue: Binding<String> {
        get: { wrappedValue },
        set: { wrappedValue = $0 }

It’s worth stopping to step through what that code does: when our binding is written to we update wrappedValue, which in turn triggers our nonmutating setter, which is what causes the new value to be written to disk.

And now we can update ContentView to bind a TextEditor directly to our document, like this:

TextEditor(text: $document)

If you run that back you’ll see every change you make is immediately saved, and will also be restored when you relaunch the app. Nice!


If you want to take this tutorial further, here are some suggestions:

  1. Rather than have our binding write to disk every time a single character is changed, can you write code that simply sets a dirty flag and handle the writing at a later date? This might be periodically using Timer, or perhaps even by detecting the app moving to the background.
  2. Can you think of a way for our property wrapper to detect external changes, and reload itself in that case? For example, if someone else modifies the file, our wrapper should detect that and load the modified file. This might be as simple as a timer checking when the file was last modified.

If you liked this, you'd love Hacking with Swift+…

Here's just a sample of the other tutorials, with each one coming as an article to read and as a 4K Ultra HD video.

Find out more and subscribe here

Shadows and glows



FREE: Shadows and glows

SwiftUI gives us a modifier to make simple shadows, but if you want something more advanced such as inner shadows or glows, you need to do extra work. In this article I’ll show you how to get both those effects and more in a customizable, flexible way.




FREE: Trees

Trees are an extraordinarily simple, extraordinarily useful data type, and in this article we’ll make a complete tree data type using Swift in just a few minutes. But rather than just stop there, we’re going to do something quite beautiful that I hope will blow your mind while teaching you something useful.

Using memoization to speed up slow functions



FREE: Using memoization to speed up slow functions

In this article you’ll learn how memoization can dramatically boost the performance of slow functions, and how easy Swift makes it thanks to its generics and closures.

Creating a WaveView to draw smooth waveforms



FREE: Creating a WaveView to draw smooth waveforms

In this article I’m going to walk you through building a WaveView with SwiftUI, allowing us to create beautiful waveform-like effects to bring your user interface to life.

Ultimate Portfolio App: Introduction



FREE: Ultimate Portfolio App: Introduction

While I’m sure you’re keen to get started programming immediately, please give me a few minutes to outline the goals of this course and explain why it’s different from other courses I’ve written.

How to use phantom types in Swift



FREE: How to use phantom types in Swift

Phantom types are a powerful way to give the Swift compiler extra information about our code so that it can stop us from making mistakes. In this article I’m going to explain how they work and why you’d want them, as well as providing lots of hands-on examples you can try.

Understanding generics – part 1



FREE: Understanding generics – part 1

Generics are one of the most powerful features of Swift, allowing us to write code once and reuse it in many ways. In this article we’ll explore how they work, why adding constraints actually helps us write more code, and how generics help solve one of the biggest problems in Swift.

User-friendly network access



FREE: User-friendly network access

Anyone can write Swift code to fetch network data, but much harder is knowing how to write code to do it respectfully. In this article we’ll look at building a considerate network stack, taking into account the user’s connection, preferences, and more.

Making your app accessible



FREE: Making your app accessible

It is my firm belief that every iOS app should be usable to everyone, and putting in the work to make your app function well no matter who is using it says a lot about the kind of developer you are.

Making the most of optionals



FREE: Making the most of optionals

Swift’s optionals are implemented as simple enums, with just a little compiler magic sprinkled around as syntactic sugar. However, they do much more than people realize, and in this article I’m going to demonstrate some of their power features that can really help you write better code – and blow your mind along the way.

Flocking with boids



Flocking with boids

If you watch a flock of birds you’ll see it exhibits all sorts of complex behaviors as they swarm around in the air – they often stay together but not too close, they move in the same direction but also seem to change direction at the same time. In this article we will create flocking behavior in SwiftUI, using Craig Reynolds’ classic boids algorithm.

Rendering a line chart



Rendering a line chart

Line charts come in a couple of different forms, but they share the same goal of visualizing a change of value over time. In this article we’ll look at building a customizable line chart from scratch in SwiftUI.

Questions and answers, part 1



Questions and answers, part 1

As folks have worked their way through the series so far, they’ve sent in various questions about implementation choices and more. In this article I want to address the eight most common questions asked so far, so that everyone can benefit.

Remaking the iOS lock screen



Remaking the iOS lock screen

In this article we’re going to look at how easy it is to rebuild the iOS lock screen. Yes, this isn’t hard, but along the way I think you’ll pick up a few cool SwiftUI tricks, including better date formatting, haptic buttons, and more.

Existentials and type erasure – part 1



Existentials and type erasure – part 1

Type erasure helps us solve difficult type system problems by purposefully discarding some information. In this article we’ll look at what the underlying problem is and how Swift solves it, and in the second part we’ll continue on to look at how we can build type erasure ourselves.

Linked lists



Linked lists

If there’s one data structure they just love teaching you at school, it’s linked lists. In this article we’re going to look at why linked lists are so appealing, walk through how to build a linked list with Swift, and look at an alternative approach using enums.

Basic button customization using ButtonStyle



Basic button customization using ButtonStyle

SwiftUI’s humble Button view is actually capable of doing remarkable things if you take the time to customize it. In this video I’ll be walking you through the ButtonStyle protocol, showing you how we can use it to make great-looking and reusable button effects.

Questions and answers, part 2



Questions and answers, part 2

I’ve had a whole bunch more questions sent in from readers, covering Core Data, property wrappers, localization, and more, so let’s dive into them with some code examples.

Understanding assertions



Understanding assertions

Assertions allow us to have Swift silently check the state of our program at runtime, but if you want to get them right you need to understand some intricacies. In this article I’ll walk you through the five ways we can make assertions in Swift, and provide clear advice on which to use and when.

Advanced string interpolation, part two



Advanced string interpolation, part two

In part one of this tutorial we looked at how to customize string interpolations on a type-by-type basis, giving you more control over how your code works. In this second part we’ll look at a second powerful use for interpolation: building whole types from scratch.

Unknown user

You are not logged in

Log in or create account

Link copied to your pasteboard.