How the TypeScript Exclude Type Works

In TypeScript, the Exclude utility type lets us exclude certain members from an already defined union type. That means we can take an existing type, and remove items from it for specific situations.

Let's look at how the exclude utility type works in TypeScript.

Utility Types

Utility Types are types defined in TypeScript to solve particular problems. If you're new to defining custom types in TypeScript, read my guide on defining custom types here.

How the Exclude Type Works in TypeScript

In TypeScript, we can define a specific type called a union type. A union type is a list of possible values for something. For example:

type myUnionType = "x" | "y" | "z" | "a"

Above, if we give something the type myUnionType, then it will only be able to be 4 values: x, y, z or a. For example:

type myUnionType = "x" | "y" | "z" | "a"

// This works!
let myString:myUnionType = "x"

// This throws an error! "Type '"some-string"' is not assignable to type 'myUnionType'.
let secondString:myUnionType = "some-string"

So now we've covered the basics of how union types work, let's talk about Exclude.

The Exclude Type

Suppose we have a situation where we want to use myUnionType, but we don't want to include 'a' in the valid list of values. This can happen in real life in an API response - suppose you have a standard API response type, but you want to remove a field in a particular situation from that API type.

That's where we can use Exclude. Exclude has the syntax Exclude<UnionType, ExcludedMembers>. We pass in our normal union type, and then say which members we want to remove from it in the second argument.

Let's try it:

type myUnionType = "x" | "y" | "z" | "a"

// This works!
let lemon:myUnionType = "a"

// This throws an error! Type '"a"' is not assignable to type '"x" | "y" | "z"'.
let noLemonsPlease:Exclude<MyUnionType, "a"> = "a"

The second variable, noLemonsPlease throws an error, since we used Exclude to remove 'a' from our union type for this specific variable. That means we can use the type as normal elsewhere, and then exclude members when we feel like it with Exclude.

If we want to remove more than one member, we just have to separate them with a |:

type myUnionType = "x" | "y" | "z" | "a"

// This works!
let lemon:myUnionType = "a"

let noLemonsPlease:Exclude<myUnionType, "a"> = "x"
//  ^
//  └ - - Type is  "x" | "y" | "z"

let noApplesOrLemons:Exclude<myUnionType, "a" | "y"> = "x";
//  ^
//  └ - - Type is  "x" | "z"

let onlyRaspberries:Exclude<myUnionType, "a" | "y" | "z"> = "x";
//  ^
//  └ - - Type is  "x"

let backToLemons:myUnionType = "a"
//  ^
//  └ - - Type is  "x" | "y" | "z" | "a"

The Exclude type, therefore, gives us the flexibility to remove specific elements when it suits us and keep them there when we need them again.