What is a phantom type?

Learn safety with phantom type parameters.

What is a phantom type?

A phantom type is a generic type parameter that is declared but never used in the type's body. This parameter carries information only at the type level; it has no runtime representation. Its purpose is to mark values with the same structure as distinct types, catching misuse at compile time.

type Order<T> = { amount: number };
// T is not used in the body: phantom

type PendingOrder = Order<"pending">;
type PaidOrder = Order<"paid">;

Nominal-like safety with phantoms

The phantom parameter replaces the marker field of branded types. Two values with the same structure but different phantom arguments become distinct types; this prevents mixing them at compile time. At runtime the values are identical.

type Order<T> = { amount: number };

const pending: Order<"pending"> = { amount: 10 };
const paid: Order<"paid"> = { amount: 10 };

const x: Order<"paid"> = pending;  // error: types differ

Exercise Separate two types with phantoms

Define a generic type Order<T> that doesn't use T in its body (body has amount: number). Create PendingOrder and PaidOrder types with phantom arguments. Create a value of each type and print both amount values via console.log.

Show example solution

type Order<T> = { amount: number };

type PendingOrder = Order<"pending">;
type PaidOrder = Order<"paid">;

const pending: PendingOrder = { amount: 10 };
const paid: PaidOrder = { amount: 20 };

console.log(pending.amount);
console.log(paid.amount);

Test yourself

What property does a phantom type parameter have?
- It is ignored at compile time
- It is never used in the type's body
- It carries a value at runtime
- It can only be used in classes
Show answer

It is never used in the type's body — A phantom parameter is declared as generic but never used in the type's body; therefore it works only as a type-level marker.

Phantom type body

type Order<T> = { ____ };  // T gövdede yok: phantom

Show answer

type Order<T> = { amount: number };  // T gövdede yok: phantom

Phantom type parts

Generic parametre

not used in type body
Phantom type

type-level marker only
Farklı phantom argümanlar

create distinct types
Çalışma zamanı

no phantom parameter at runtime

Next lesson: State Encoding

We Are Enhancing Your Experience

Cookie Preferences

Strictly Necessary Cookies

Analytical Cookies