Narrow allowed values
Derive a permitted-operation union by removing administrative or deprecated operations from a broader union.
TypeScript · Type Alias
Exclude
Exclude<UnionType, ExcludedMembers> creates a type by removing from a union every member assignable to the excluded type. It is globally available and useful for deriving narrower unions.
- Since
- 2.8
How it works
Exclude<UnionType, ExcludedMembers> evaluates each member of a union and removes the members assignable to ExcludedMembers. It is a global utility type and is especially useful for deriving a narrower union from an existing one without repeating every remaining member.
Syntax
Exclude<UnionType, ExcludedMembers>Parameters
| Name | Type | Description |
|---|---|---|
UnionType | type | The union whose members are tested and potentially removed. |
ExcludedMembers | type | The type to which union members are compared for assignability. |
Returns
A type containing the members of UnionType that are not assignable to ExcludedMembers; removed members contribute never.
Key points
- You can use
Excludewithout importing it from a module because TypeScript supplies it as a global utility type. - Its type-level signature takes the source union first and the members to remove second.
- The result keeps source-union members that are not assignable to the excluded type.
Common mistakes
- Exclude removes union members assignable to the second type; it does not remove arbitrary structural fragments from a member.
Example: Exclude one union member
type Access = "read" | "write" | "admin";
type NonAdminAccess = Exclude<Access, "admin">;
const access: NonAdminAccess = "read";
console.log(access);NonAdminAccess contains only the union members that are not assignable to "admin".
When to use it
Separate internal and external variants
Create a public API type from an internal union while excluding implementation-only variants.
Filter union members
Filter discriminated object unions by excluding members matching a discriminant shape.
Interview questions
QWhat does TypeScript's Exclude utility type do?
Exclude<T, U> constructs a type from T by removing union members assignable to U. For example, Exclude<"a" | "b", "a"> produces "b".
Follow-up: How does it relate to conditional types? It is a predefined conditional type whose behavior distributes across a union.
QDoes Exclude remove properties from object types?
It operates on union members, not on individual properties inside an object type. If an object union member is assignable to the excluded object type, that whole member is removed.
Follow-up: What happens with a non-union input? It is either retained or replaced with never, according to whether it is assignable to the excluded type.
QWhen was Exclude introduced, and how is it implemented conceptually?
Exclude is globally available and was introduced in TypeScript 2.8. Its declaration is conceptually type Exclude<T, U> = T extends U ? never : T.
Follow-up: Why does the conditional distribute? A naked type parameter on the left side of extends is evaluated separately for each union constituent.
Related
ExtractNonNullablePickOmitConditional Types