Exclude<T, U> Exclude (with Extract)
Last updated: 2026-10-22
Exclude<T, U> Exclude (with Extract)
Exclude<T, U> removes members of union T that are assignable to U — typically trimming branches you do not care about from a big union. Its mirror Extract<T, U> keeps only members assignable to U. Both rely on the distributive behavior of conditional types.
| Group | Utility Types |
|---|---|
| Kind | Type |
| Strict mode | Not required |
ℹ️ Info The editor transpiles TypeScript to JavaScript and runs it (no type checking); see each example's Output for type-check results.
📝 Syntax
type Exclude<T, U> = T extends U ? never : T;
type Extract<T, U> = T extends U ? T : never;
// Usage
type PassiveEvent = Exclude<EventType, "click" | "keydown">;
type Interactive = Extract<EventType, "click" | "keydown">;⚙️ Parameters
| T | The source union; each member is tested by the conditional type in turn (distributivity) |
|---|---|
| U | The filter: members assignable to U are removed (Exclude) or kept (Extract) |
Returns：A new union type: Exclude is the difference T minus U; Extract is the intersection of T and U.
▶ Example
Edit the code below and click Try it to see the transpiled result:
Output：
focus | scroll | wheel
click | keydown
(Runtime output after transpilation; the type-level effect: pushing "click" into passiveEvents is a compile error — Exclude already removed it from PassiveEvent)💡 Notes
ℹ️ Info It works via distributive conditional types: when T is a union, T extends U is evaluated per member and the results recombined. A member matching U becomes never (vanishing from the union) — that is how "exclusion" is implemented.
⚠️ Note These tools are meaningful only on union types. Applying them to a non-union object type does not process properties one by one and defies intuition — use Omit/Pick for object properties.
💡 Tip NonNullable<T> is simply Exclude<T, null | undefined>. Knowing this, your understanding of Exclude transfers over directly.
🏷️ Related Utility Types
💡 Related cases
More cases coming soon.
📚 Related tutorials
❓ FAQ
Q How does Exclude differ from Omit?
A Exclude operates on union members; Omit operates on object property keys. Omit is in fact implemented via Exclude: Exclude<keyof T, K> trims the keys before Pick. One manages members, the other keys.
Q Why "distributive"? What if it did not distribute?
A Without distribution, T extends U would compare the whole "click"|"focus"|... union against U at once, find it non-assignable, and remove nothing. Distribution tests each member individually — that is the very mechanism for filtering union members.
Q Can Exclude remove object members from a union?
A Yes, as long as the member is assignable to U. For example with type Shape = Circle | Square, Exclude<Shape, Square> drops Square. The criterion is always assignability, not literal equality.
