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

< Back to Latest Articles

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.

Watch the video here, or read the article below

What are phantom types?

The basic definition of a phantom type is this: a type that doesn’t use at least one of its generic type parameters. That’s it – it’s not very complicated, at least when looking at the code.

So, this is a phantom type:

struct Employee<Role>: Equatable {
    var name: String

That is generic over some sort of Role, but Role doesn’t appear in the type’s definition – there’s only that one string.

In comparison, here is one of Apple’s Foundation APIs, slightly simplified:

struct Measurement<UnitType> {
    let unit: UnitType
    var value: Double

That is not a phantom type, no matter what you might hear elsewhere – it is generic over UnitType but that parameter is used right there for unit, so this is just a regular generic type.

So, the definition of a phantom type is simple, but the real question here is this: why the heck would you want to specify a generic parameter and never use it?

What’s the point?

Our trivial phantom type was this:

struct Employee<Role>: Equatable {
    var name: String

That doesn’t use Role at all, so we could just have used this instead:

struct Employee: Equatable {
    var name: String

However, there’s an important difference: although we don’t use the generic parameter, Swift does. This allows Swift to enforce rules for us much more strictly.

For example, if you work for a software company you might have employees who work in a coding team and other employees who work in a sales team. We can represent them with no-case enums like these:

enum Sales { }
enum Programmer { }

Tip: It’s a good idea to use a no-case enum rather than a struct, because the enum cannot be instantiated, whereas someone could create an instance of the struct and wonder what it’s good for.

Now, if you had a friend called Zoe who worked in the coding team, she might look like this:

let zoe1 = Employee<Programmer>(name: "Zoe")

And if you had another friend called Zoe who worked in the sales team, she might look like this:

let zoe2 = Employee<Sales>(name: "Zoe")

Now, we made Employee conform to Equatable, and because its single property already conforms to Equatable Swift will be able to synthesize an == function to let us compare two employees. So, we can check whether our two employees are actually the same person like this:

print(zoe1 == zoe2)

Except that won’t work – we aren’t comparing two instances of Employee any more, we’re comparing an Employee<Programmer> and an Employee<Sales>, and Swift considers them to be different. In comparison, if we had made someone’s role a string property, Swift would say that the two Zoe’s are different at runtime, but it wouldn’t stop us from compiling.

That’s the power of phantom types: we give Swift extra information that clarify how things should work, and allow it to work harder on our behalf. When done well, this will allow logic errors to be surfaced as compiler errors: Swift literally won’t build our code because what we’re trying to do doesn’t make sense.

Hands-on examples

If you were working in a hospital that analyzes blood samples, you might start by defining some of the different blood types:

enum OPositive { }
enum APositive { }
enum BPositive { }

Now you can create a BloodSample struct that is generic over some sort of blood type, like this:

struct BloodSample<Type> {
    let amount: Double

    static func +(lhs: BloodSample, rhs: BloodSample) -> BloodSample {
        BloodSample(amount: lhs.amount + rhs.amount)

That has a + operator that lets us combine two blood samples, but Swift will automatically understand that two samples from different blood types are different and stop us from mixing them by accident.

So, this code will work:

let sample1 = BloodSample<OPositive>(amount: 5)
let sample2 = BloodSample<APositive>(amount: 5)
let sample3 = BloodSample<OPositive>(amount: 7)

let combined1 = sample1 + sample3

But this will not:

let combined2 = sample1 + sample2

Sometimes the differences between types are less subtle. For example, consider a user struct like this one:

struct User {
    let id: Int
    let age: Int

Both id and age are integers, so there’s nothing stopping us from comparing them like this

let user = User(id: 53, age: 53)
print( == user.age)

I mean, yes, the two integers are identical, but if you’re comparing user IDs to ages then it’s almost certainly a mistake – and it’s a mistake phantom types can help us catch.

First, we make no-case enums to represent out variations:

enum UserID { }
enum Age { }

Next, we create a struct that is generic over some kind of type, but doesn’t actually use that type in its definition:

struct Tag<Type>: Equatable {
    var value: Int

Now we can modify the User struct so that each of its properties use Tag, like this:

struct User {
    let id: Tag<UserID>
    let age: Tag<Age>

    init(id: Int, age: Int) { = Tag(value: id)
        self.age = Tag(value: age)

And now trying to compare id and age simply won’t work.

In practice, I’d prefer to change that a little so that Tag conformed to the ExpressibleByIntegerLiteral protocol like this:

struct Tag<Type>: Equatable, ExpressibleByIntegerLiteral {
    init(integerLiteral value: Int) {
        self.value = value

    var value: Int

That allows Swift to make instances of Tag directly from an integer, so we can simplify all the types that use Tag so they rely on Swift’s synthesized memberwise initializer:

struct User {
    let id: Tag<UserID>
    let age: Tag<Age>

For a broader solution to this same problem, see my article Improving your Swift code using value objects.

The most important thing to remember is that although our phantom types are empty, the Swift compiler is fully aware of them. So, you can use them as constraints in extensions and more – they aren’t special.

Building a state machine

There are lots of practical ways you can use phantom types to build interesting stuff, and I came across one fascinating experiment from Soroush Khanlou. In his example, Soroush uses phantom types to build a state machine where invalid transitions can’t compile – Swift won’t allow it.

Tip: State machines are pieces of code that are designed to move between a series of predefined states. For example, a vending machine might move between the states “waiting for customer”, “coin inserted”, “fetching selection” and “serving selection”. It wouldn’t make sense for the vending machine to go from “waiting for customer” to “serving selection”, because no coin was inserted.

Soroush very kindly gave me permission to use his code here, although I’m going to simplify a little so we can focus on the part that matters.

First, we create the various states our machine can be in. For this example we’ll have have the four that represent a vending machine:

enum Waiting {}
enum CoinInserted {}
enum Fetching {}
enum Serving {}

Second, we create a phantom type to store a transition between two states:

struct Transition<From, To> {}

Neither of those types are used – the struct is literally empty. But that’s okay, because Swift is still able to track them.

Third, we’ll create a Machine struct that represents our state machine in one given state. This has one method that will transition from the current state to a new state, like this:

struct Machine<State> {
    func transition<To>(with transition: Transition<State, To>) -> Machine<To> {

That’s doing a lot of work in hardly any code, so let’s break it down:

  • The Machine struct is generic over some kind of State.
  • The transition() method is generic over some kind of To, but also relies on the State generic parameter from Machine.
  • We’re telling Swift the transition must be from the current state of our machine, and to some other kind of state.
  • The function returns a new machine that uses the new To state.
  • Using .init() will automatically make a new Machine struct of the correct type: Machine<To>.

Now we can go ahead and create all valid transitions by specifying where they come from and where they go to, like this:

let start = Transition<Waiting, CoinInserted>()
let selectionMade = Transition<CoinInserted, Fetching>()
let delivery = Transition<Fetching, Serving>()
let reset = Transition<Serving, Waiting>()

And that’s it! We can now create a Machine with a particular state, and step it through any other possible valid state, like this:

let m1 = Machine<Waiting>()
let m2 = m1.transition(with: start)
let m3 = m2.transition(with: selectionMade)
let m4 = m3.transition(with: delivery)
let m5 = m4.transition(with: reset)

The magic here is that Swift will check all those transitions at compile time – it’s not possible to make an illegal transition.

For example, this won’t compile:

let m6 = m5.transition(with: delivery)

The problem is that m5 is a Machine<Waiting>, so we can’t go straight from there to a Machine<Serving>.

I think this is a fantastic experiment, because it shows how we can leverage the Swift compiler to prove that our code is correct. Plus, it makes for a fascinating exploration of phantom types in action.

However, in practice this solution doesn’t work so well. To explain why, I asked Soroush himself – here’s what he said:

“I originally wrote this as an experiment to see if I could have the compiler protect me from performing invalid transitions on a state machine, but I quickly realized that changes to the state would cause the type of the entire machine to change, meaning that it couldn’t be stored back into the same variable. This prevents you from having it as a property on, say, a view controller, with transitions modifying the state machine. So: fun to try out, a little impractical in actual usage.”

Undefined as a type

Before I finish, there’s one more technique I want to demonstrate, and it’s quite different from all the earlier examples. It’s this piece of code:

func undefined<T>(_ message: String = "") -> T {
    fatalError("Undefined: \(message)")

That isn’t a phantom type, but it is a great example of using Swift’s type system in interesting ways. I first saw this being used by Johannes Weiss from the SwiftNIO team, where he presented this as a useful global function to have around while you’re still building your app.

This function, undefined<T>(), can act as pretty much any other kind of value you want, because it is generic over T and promises to return a T. It won’t actually return a T, but it doesn’t need to: calling fatalError() is enough to see that nothing needs to be returned.

This set up it can act as a placeholder to make your code compile when you’re part-way through your work and don’t want to fill in all the various parts just yet.

You can make simple instances of types using undefined(), like this:

let name: String = undefined("Example string")
let score: Int = undefined("Example int")

You can make it act as a placeholder inside a function you haven’t written yet:

func userID(for username: String) -> Int? {

In that instance you could use fatalError() to mark the missing code, but then again fatalError() does have legitimate uses outside of marking unfinished work so it becomes harder to find and replace later.

And you can even use it repeatedly when there are lots of parameters you haven’t filled in yet:

let timer = Timer(timeInterval: undefined(), target: undefined(), selector: undefined(), userInfo: undefined(), repeats: undefined())

Obviously many of these places could be replaced with hard-coded placeholders, such as 0 or an empty string, but the magic of undefined() is that it will crash as soon as it’s touched – it will work only at compile time, to help you move your project forward, but can’t possibly work at runtime. Also, it’s easier to search your code for “undefined” than some magic value!

Of course, you might have the question “if undefined<T>() isn’t a phantom type, what is it?” And to be honest I had exactly the same question, so I went back to the source and asked Johannes. Here’s what he said:

I wouldn't call undefined<T>() a phantom type because first of all, really it's a value. Well, a value that we'll never generate, but still. Even calling T a phantom type isn't quite right: T can be anything, so it could be a String which is far from a phantom type. I think the closest somewhat correct term I have for this is that it's called the "bottom value", usually written like ⏊, and even that is probably not right because the "bottom type" is defined as not having values! So the term "bottom value" isn't great either, but I guess we could say "undefined's return type is bottom"?

I love that answer, because it shows just how nuanced the discussion is.

Anyway, that finishes up our discussion about phantom types. You’ve seen how they work and I’ve given you some hands-on examples, plus I’ve walked you through how we can build state machines using them as an interesting experiment, and even how we can create simple placeholder functions that can act as helpers to make our code compile while we’re still working. They might not be phantom types, but they are still fascinating!

Further reading

Phantom types are a fascinating area of discussion, and there’s a lot of high-quality material I recommend you check out.

First, Johannes Weiss delivered the talk that originally introduced to me to phantom types in Swift: The Type System is Your Friend. He also introduced the undefined() function there, although I recommend you check out his repository on GitHub because it’s a little more advanced.

Second, Brandon Case delivered a talk called Strings Are Evil, where he builds a file-handling system where phantom types make it impossible to created badly-formed file paths.

Third, if the idea of tagged integers interested you, you might want to check out the Tagged repository on GitHub, which takes the concept significantly further. As an alternative, you should check out my article Improving your Swift code using value objects.

Fourth, I walked you through a simplified version of Soroush Khanlou’s state machine, but if you’d like to read the full version it’s in this GitHub Gist

Finally, Ole Begemann walks through what it would look like to rewrite Apple’s Measurement API using phantom types in this article: Measurements and Units with Phantom Types


If you’d like to take your knowledge of phantom types further, try creating phantom types to solve these problems:

  1. A Temperature type that is generic over whether it uses Celsius or Fahrenheit.
  2. A Car type that is generic over whether it uses diesel or gas for the engine.

I also have a question that I’d like you to consider: what benefits of phantom types could we gain by using a class hierarchy instead? Just as importantly, what benefits would we lose?

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

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.

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.

Creating a custom property wrapper using DynamicProperty



FREE: 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.

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.

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.

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.

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.

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.

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.

Customizing Toggle using ToggleStyle



Customizing Toggle using ToggleStyle

Most of the time the built-in iOS controls are great, but sometimes you want something just a little different. In this article I’m going to walk you through how you can take complete control over the way toggle switches work in SwiftUI, providing custom rendering and interactions.

Designing a great model



Designing a great model

Almost always, the key to getting a great app is getting a great data model – deciding as early as you can what data you want to store, and how each piece relates to other pieces. So, we’re going to dive straight into Core Data!

Converting measurements safely



Converting measurements safely

Apple’s Foundation framework makes it easy for us to convert any kind of measurement into any other kind of measurement. In this article I’ll show you how to make the most of these APIs, but also why it’s so useful that they work with Swift features such as operator overloading, plus important protocols such as Comparable, Equatable, and Codable.

Testing the basics



Testing the basics

At last it’s time to start writing tests for our project, which means a little bit of setup work backed by writing our first couple of tests – we’ll take this slow initially, but lay down a good foundation for future tests.

Why opaque return types are so important



Why opaque return types are so important

Opaque return types are a powerful feature in Swift, and are also critically important for writing SwiftUI. In this article I’ll be explaining how they work, and why they give us more power than returning a simple protocol.

Removing optionals from your code



Removing optionals from your code

Optionals are one of Swift’s most powerful features, letting us write code that is guaranteed to be safe as long as we check and unwrap them carefully. However, more often than not I prefer to avoid optionals as often as possible, and in this article I’ll outline some approaches for doing so.

Creating a FlipView to provide a card flip effect



Creating a FlipView to provide a card flip effect

If you’re looking for a simple and fun special effect to add to your code, I’ve got just the thing for you. In this article I’m going to walk you through building a FlipView with SwiftUI, which will encapsulate how to move between a front view and a back view using a 3D flip animation.

Controlling views using the accelerometer



Controlling views using the accelerometer

Reading device motion and orientation is a fast and slightly magical way to incorporate the real world into your apps, and can do a huge amount to add a little spark of delight to your UI. In this article I’m going to show you how easy it is to control SwiftUI layouts using the accelerometer, and give you a few ideas for special effects.

Unknown user

You are not logged in

Log in or create account

Link copied to your pasteboard.