For a named object shape that may grow or serve as a public contract, prefer an interface. Use a type alias when you need to name a union, tuple, primitive, or other type expression that an interface cannot represent. Both can describe ordinary object shapes, so the choice is about capabilities and API behavior—not a runtime difference.
How interfaces and type aliases differ
An interface declares the members an object shape has. A type alias gives a name to a type expression: that expression can be an object shape, but it can also be a primitive, union, tuple, or combination of types. An alias does not create a distinct nominal type; it is another name for the underlying type.
For example, both declarations can describe an object with a string name:
interface User {
name: string;
}
type UserAlias = {
name: string;
};For this simple shape, either form works. The distinction becomes useful when you need to extend declarations, combine shapes, or describe alternatives. The TypeScript Handbook recommends using an interface over a type alias when possible, because interfaces are open to extension.
#1 Best Overall
When should you use an interface?
For an extendable object contract
An interface can extend one or more types, adding their members to a related shape without repeating those declarations:
interface HasId {
id: string;
}
interface User extends HasId {
name: string;
}Here, User has both id and name. The extends relationship also makes the connection between the two shapes explicit. If inherited properties conflict, TypeScript reports an error rather than silently making the property impossible to satisfy. See the Handbook’s guidance on interface extension versus intersection.
Rank #2
- TypeScript implements a superset of syntax for strictly typed development, facilitating deep static analysis and enhanced development environment integration. The compiler translates source into standard script formats, ensuring parity across any runtime.
- TypeScript is ideal for front-end developers, full-stack engineers, and software architects who build large-scale web applications. It serves those looking to improve code excellence, reduce bugs through static checking, and maintain complex projects more.
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
When declaration merging is intentional
Two interface declarations with the same name can merge into one interface:
interface Options {
timeout: number;
}
interface Options {
retries: number;
}The resulting Options shape has both properties. This can provide an extension point for ambient declarations or consumers augmenting an existing contract. It should be deliberate: a declaration in scope can change the final shape. Repeated non-function members must have compatible types; a conflicting type produces an error. Same-named type aliases do not merge. The Handbook documents these rules in its section on merging interfaces.
Free tools Windows power users keep installed
One-click scans. No signup required.
When should you use a type alias?
For unions and alternative states
A union describes a value that may be one of several alternatives. For example, a result can either contain data or an error:
type Result =
| { state: "success"; value: string }
| { state: "error"; message: string };Before narrowing, code can safely access only members common to all alternatives. Checking the shared state discriminant lets TypeScript narrow the value to the matching case. An interface describes a single object shape; it does not directly express this union. The Handbook explains union types and narrowing.
For tuples and other type expressions
Use a type alias to name a tuple, primitive, or other expression that is not simply an interface-shaped object:
type Coordinates = [number, number];
type UserId = string;These aliases name existing types; they do not make Coordinates or UserId nominally distinct from the types they refer to. Type aliases can also describe generic or recursive types, including recursive references through object properties. The Handbook covers the broader scope of type aliases.
Best Value
Should you extend an interface or intersect types?
interface extends and the intersection operator & can both combine object members, but they handle incompatible properties differently. With extension, an incompatible inherited declaration is an error. With an intersection, the resulting property must satisfy both types.
interface TextValue {
value: string;
}
interface NumericValue {
value: number;
}
// Error: the inherited value declarations conflict.
interface InvalidValue extends TextValue, NumericValue {}
type CombinedValue = TextValue & NumericValue;
// CombinedValue["value"] must be both string and number,
// so the property is effectively never.An intersection is useful when composing reusable pieces that do not conflict. If two components define the same property, inspect whether their types are compatible: an impossible intersection can make the resulting property unusable. The Handbook describes the distinction between extension and intersection.
Quick Recap
Quick decision guide
| Need | Prefer | Why |
|---|---|---|
| A named object shape that may be extended | interface |
Supports extends and declaration merging. |
| A union of alternatives or a discriminated state | type |
A type alias can name a union. |
| A tuple, primitive, or other type expression | type |
Aliases can name forms an interface cannot express. |
| Combining object pieces with a clear inheritance relationship | interface extends |
Expresses the relationship and catches incompatible inherited properties. |
Composing reusable types with & |
type |
Intersections combine requirements; check for colliding properties that become impossible. |
| An intentional extension point for consumers or ambient declarations | interface |
Same-name declarations can merge, changing the resulting shape. |
| Equivalent, closed object shapes in one codebase | Either | Follow the surrounding project’s convention. |
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
