Syntax
interface Name { }
type Name = { };Examples
Declaration Merging - interface Only
A capability unique to interfaces, often used to extend third-party library types.
interface Window {
myCustomProperty: string;
}
interface Window {
anotherProperty: number;
}
// TypeScript automatically merges both declarations -
// Window now has BOTH myCustomProperty and anotherProperty
// This is impossible with type - a duplicate type alias name is a compile errorWhat type Can Do That interface Cannot
Unions, tuples, and primitive aliases are exclusive to type.
type Status = "pending" | "active"; // interface cannot express a union like this
type Point = [number, number]; // interface cannot express a tuple like this
type ID = string | number; // interface cannot alias a primitive unionBest practices
- For plain object shapes, either works - many teams default to interface for public APIs and type for everything else, but consistency matters more than the specific choice
- Use interface specifically when you need declaration merging, such as augmenting a type from a third-party library
- Use type when you need a union, tuple, or an alias for a primitive - interface simply cannot express these
- Within a single codebase, pick one convention for object shapes and apply it consistently, rather than mixing arbitrarily
At a glance
- Purpose
- Static types for JavaScript
- File extension
- .ts · .tsx
- Runs in
- Compiled to JavaScript
- Usually used with
- JavaScript and its ecosystem
Specifications & further reading
Related TypeScript documentation
Interfaces
Interfaces in TypeScript define the structure of objects by specifying property names and their types. They act as contracts that ensure objects conform to specific shapes, providing type safety and better IDE support. Interfaces can be extended, merged, and used to type-check function parameters, return values, and object literals.Index Signatures
An index signature lets an interface or type describe an object with dynamic keys of a known type, when you don't know the exact property names in advance - only their pattern. This is common for dictionary-like objects, such as a lookup table keyed by user ID or product SKU.Basic Types
TypeScript extends JavaScript with static types, letting the compiler catch type errors before code ever runs. Beyond the familiar string, number, and boolean, TypeScript adds any (disables checking entirely), unknown (a safer any that requires narrowing), void (a function returning nothing), and never (a value that can never occur, like a function that always throws).Type Aliases
The type keyword creates a named alias for any type - not just object shapes like interface, but also unions, primitives, tuples, and function signatures. Type aliases make complex types reusable and give them a meaningful name, improving both readability and error messages.
Interfaces in TypeScript define the structure of objects by specifying property names and their types. They act as contracts that ensure objects conform to specific shapes, providing type safety and better IDE support. Interfaces can be extended, merged, and used to type-check function parameters, return values, and object literals.Index Signatures
An index signature lets an interface or type describe an object with dynamic keys of a known type, when you don't know the exact property names in advance - only their pattern. This is common for dictionary-like objects, such as a lookup table keyed by user ID or product SKU.Basic Types
TypeScript extends JavaScript with static types, letting the compiler catch type errors before code ever runs. Beyond the familiar string, number, and boolean, TypeScript adds any (disables checking entirely), unknown (a safer any that requires narrowing), void (a function returning nothing), and never (a value that can never occur, like a function that always throws).Type Aliases
The type keyword creates a named alias for any type - not just object shapes like interface, but also unions, primitives, tuples, and function signatures. Type aliases make complex types reusable and give them a meaningful name, improving both readability and error messages.