Type aliases vs interfaces
Two ways to name a type: what `type` can express that `interface` can't, where interfaces behave differently, and how to choose between them.
Object types, optional and readonly propertiesUnion and literal types
Type aliases vs interfaces
The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.
Not started
What you'll learn
- A type alias gives a name to any type at all, including unions, tuples, primitives and function types; an interface can only name an object shape.
- For a plain object shape the two are nearly interchangeable, and a value typed by one can be assigned to the other as long as the shapes match.
- Interfaces are open: two `interface` declarations with the same name merge into one, while a second `type` with the same name is a duplicate-identifier error.
- Interfaces compose with `extends`, which reports conflicting properties as errors and is cheaper for the compiler; aliases compose with `&`, which silently produces `never` for conflicts.
- An object type written as an alias is assignable to `Record<string, unknown>`, but an interface with the same members is not, because interfaces can be extended later and so get no implicit index signature.
- Either default is defensible; what matters is picking one convention for a codebase and reaching for the other when you need what only it can do.
Why types need names
Once a shape shows up in more than one place, writing it out inline gets old fast:
function save(user: { id: number; name: string; email: string }) {}
function render(user: { id: number; name: string; email: string }) {}
Change one field and you have to hunt down every copy. The fix is the same as for repeated values: give it a name. TypeScript offers two ways to do that, and the fact that there are two is the source of a long-running argument. The good news is that the differences are small and concrete.
Two ways to name an object shape
type UserAlias = { id: number; name: string };
interface UserInterface {
id: number;
name: string;
}
const a: UserAlias = { id: 1, name: "Ada" };
const b: UserInterface = a; // fine: same shape
For a plain object shape, these behave the same in nearly every way. Both support optional and readonly members, methods, and call signatures. Because TypeScript compares types by structure rather than by name, a value of one is assignable to the other whenever the shapes line up. That point gets its own lesson in structural typing.
What only a type alias can do
A type alias is a name for any type expression. An interface is specifically a declaration of an object type. So anything that isn’t an object shape needs an alias:
type ID = string | number; // union
type Point = [x: number, y: number]; // tuple
type Formatter = (value: number) => string; // function type
type Status = "idle" | "loading" | "done"; // literal union
None of these can be written as an interface. The same goes for the computed types you’ll meet later in the type-level programming group: mapped types, conditional types and template literal types all live behind aliases.
Think of an alias as a label you stick on a box, whatever is in the box. An interface is a specific kind of box, one with named compartments.
What only an interface does
Interfaces are open. Declare the same interface name twice in one scope and TypeScript merges the two into one shape. Do it with type and you get Duplicate identifier. That openness is what lets libraries and global type definitions be extended from the outside, and it’s also a trap if you reuse a name by accident. Declaration merging covers the rules.
Interfaces compose with extends. An interface can extend other interfaces, and the compiler checks that the new members are compatible with the inherited ones. Aliases combine with the intersection operator & instead, which doesn’t report conflicts the same way and is more work for the compiler to check. The next lesson compares the two side by side.
Interfaces get no implicit index signature. This one surprises people:
type UserT = { id: number; name: string };
interface UserI { id: number; name: string }
function logFields(fields: Record<string, unknown>) {}
declare const t: UserT;
declare const i: UserI;
logFields(t); // fine
logFields(i);
// Error: Argument of type 'UserI' is not assignable to parameter of type 'Record<string, unknown>'.
// Index signature for type 'string' is missing in type 'UserI'.
Because an interface might gain new members through merging, TypeScript won’t assume its members fit an open-ended string-keyed type. An alias’s members are fixed when it’s written, so the compiler is willing to make that assumption. Index signatures and Record explains what that target type means.
Error messages and hovers
Interfaces always show up by name in hovers and errors. An alias for an object type usually does too, but aliases built from intersections or other computed types sometimes get expanded into their full structure. On a large type that can turn a one-line message into a wall of properties. It’s a readability difference, not a correctness one, and it’s one reason some teams prefer interfaces for big domain models.
So which one?
The TypeScript handbook’s guidance is to use interface until you need something only type can express. Plenty of experienced teams do the opposite and default to type, reaching for interface when they want extends or merging. Both positions are reasonable:
- Default to
interfaceand you get conflict-checked inheritance, consistent names in errors, and fewer intersection costs, but you can merge two declarations by accident. - Default to
typeand you get one keyword for everything and no surprise merging, but you’ll be writing&whereextendswould check more.
What actually costs time is mixing the two at random. Pick a default, write it down in your lint config or contributing guide, and switch only when you need the other’s specific behaviour.
About the video
Matt Pocock revisits advice he gave in 2022 on this exact question and checks it against what he’s learned since. He looks at the performance argument for interfaces over intersections, what benchmarks show about how much it matters in practice, and the pitfalls of declaration merging, before landing on his current recommendation. The video argues for a position, so read it alongside the trade-off list above rather than as the only answer. His older 2022 video on the same topic is marked deprecated; this one replaces it.
Check yourself
You need a name for `"idle" | "loading" | "done"`. Can you write it as an interface, and why or why not?
No. An interface always describes an object shape with members, and a union of string literals isn't an object shape. Only a type alias, `type Status = "idle" | "loading" | "done"`, can name it.
What happens if a file declares `interface User { name: string }` and later `interface User { email: string }`, and what if you do the same with `type`?
The two interfaces merge, so `User` requires both `name` and `email`. Declaring `type User` twice is an error, `Duplicate identifier 'User'`, because an alias is a single name bound to a single type and can't be reopened.
Why might a function that accepts `Record<string, unknown>` reject a value typed with an interface but accept the same value typed with an object-literal alias?
TypeScript gives object-literal alias types an implicit index signature, since their set of members is final. An interface can gain members later through merging, so the compiler won't assume every property fits `unknown` under arbitrary string keys and reports that the index signature is missing.
A teammate says interfaces and type aliases are just two spellings of the same thing. Where is that roughly right and where is it wrong?
It's roughly right for plain object shapes, which either can describe and which are compared structurally either way. It's wrong at the edges: only aliases can name unions, tuples, primitives and computed types, and only interfaces merge across declarations, use `extends` with conflict checking, and lack an implicit index signature.
Go deeper
Notes
Notes are saved to your account.
Everything else on this page works without one — progress and bookmarks keep themselves in this browser and come with you when you sign in. Notes are the one thing worth not trusting to a browser you might clear.
Your notes could not be loaded.