Type aliases & interfaces

Write a type once, use its name everywhere

A shop page has two small functions. One builds a label for a product, like Tea: $3. The other adds up a cart. Both take products, so both write out what a product is:

1function productLabel(product: { name: string; price: number }) {2  return `${product.name}: $${product.price}`;3}4 5function cartTotal(items: { name: string; price: number }[]) {6  let total = 0;7  for (const item of items) total += item.price;8  return total;9}10 11console.log(productLabel({ name: "Tea", price: 3 }));12console.log(cartTotal([{ name: "Tea", price: 3 }, { name: "Cake", price: 4 }]));

Line 1 says productLabel takes a product with a name that is a string and a price that is a number. Line 2 builds the label with a template literal. Line 5 writes the same shape again, with [] after it: cartTotal takes a list of those products. Lines 6 to 8 add up the prices. Line 11 prints Tea: $3 and line 12 prints 7. There are no errors.

The code works, but { name: string; price: number } appears twice. Each copy is long to read. And when products get a new property, you have to find every copy and change each one. Miss one, and two parts of the page disagree about what a product is.

TypeScript lets you give a type a name. You write the type once, and then use the name wherever the type goes. A name made with the type keyword is called a type alias. ("Alias" means "another name for the same thing".) Here is the same code with one:

1type Product = { name: string; price: number };2 3function productLabel(product: Product) {4  return `${product.name}: $${product.price}`;5}6 7function cartTotal(items: Product[]) {8  let total = 0;9  for (const item of items) total += item.price;10  return total;11}12 13const tea: Product = { name: "Tea", price: 3 };14//    ^?15const cake: Product = { name: "Cake", price: "4" };16console.log(productLabel(tea));17console.log(cartTotal([tea, cake]));

Line 1 is new: type Product = … gives the name Product to the object type. Read it as "a Product is an object with a string name and a number price". Line 3 now says product: Product, and line 7 says items: Product[], a list of products. Line 13 makes the tea, and the query on line 14 shows its type by name: const tea: Product.

Line 15 gives the cake a price in quotes, and TypeScript marks it on purpose, because it's a bug: Type 'string' is not assignable to type 'number'. That means "you're putting text where a number has to go". The name changed nothing about the checking: TypeScript looked up what Product means and checked the cake against it. Run it anyway, and line 16 prints Tea: $3, but line 17 prints 34, because 3 + "4" joins the two as text.

The name pays off when the type changes. The playground below has two products and the label function. Each button changes only line 1, the type. Watch which lines get errors:

1type Product = { name: string; price: number };2 3const tea: Product = { name: "Tea", price: 3 };4const cake: Product = { name: "Cake", price: 4 };5 6function productLabel(product: Product) {7  return `${product.name}: $${product.price}`;8}9console.log(productLabel(tea));

Add inStock changes one line, and TypeScript marks lines 3 and 4: both products are now missing inStock. Add inStock? makes it optional, with a question mark, so the errors go. Remove price marks three lines: the two objects that still have a price, and line 7, which reads one. You changed the type in one place, and TypeScript gave you a list of every place to update. The output stays Tea: $3 each time, because types never change what the code does.

Type aliases: a name for any type

A type alias is the word type, a name, an equals sign, and a type. Names of types start with a capital letter by habit, like Product, so you can tell them apart from variables. The type after the = can be any type at all, not only an object:

1type Plan = "free" | "pro";2type Email = string;3type User = { name: string; email: Email; plan: Plan };4 5const asha: User = { name: "Asha", email: "asha@example.com", plan: "pro" };6const ben: User = { name: "Ben", email: "ben@example.com", plan: "gold" };7console.log(asha.plan);

Line 1 names a union: a Plan is the exact text "free" or the exact text "pro", and nothing else (a type that is one exact value is a literal type). Line 2 gives string a second name, Email, which tells a reader what the text is for. Line 3 names an object type, and its properties use the two aliases from lines 1 and 2. Line 5 makes Asha, on the pro plan, which fits.

Line 6 puts Ben on a "gold" plan, and TypeScript marks it on purpose: Type '"gold"' is not assignable to type 'Plan'. The message uses the name, so you can read it as ""gold" isn't one of the plans". Line 7 still prints pro when it runs.

Try it yourself. The box below fills in the type on line 1 of a ProductId alias. Line 3 gives the tea the id 7, and line 4 gives the cake the id "c-4". Type different types and watch the list under the code:

1type ProductId = number;2 3const teaId: ProductId = 7;4const cakeId: ProductId = "c-4";5console.log(teaId, cakeId);

With number, the cake's text id gets an error; with string, the tea's number id does. With number | string, both fit and the errors are gone. Whatever you type, the code prints 7 c-4 when it runs: the alias only tells TypeScript what to check.

An alias doesn't make a new type. It's another name for the same type, and TypeScript treats the two as one:

1type Email = string;2 3const email: Email = "asha@example.com";4//    ^?5const loud = email.toUpperCase();6console.log(loud);

Line 1 makes Email another name for string. Line 3 says email is an Email. The query on line 4 shows const email: string: for an alias of a simple type like string, TypeScript shows the type itself. Line 5 calls a string method, and line 6 prints ASHA@EXAMPLE.COM. Any string fits an Email, even "hello", because the two names mean the same type. (The Structural typing lesson shows more of this.)

Interfaces: a name for an object shape

The second way to name a type is an interface. You write the word interface, a name, and the properties inside braces. There's no equals sign. An interface can only describe an object shape: which properties an object has, and the type of each.

1interface User {2  name: string;3  email: string;4  nickname?: string;5}6 7function greet(user: User) {8  return `Hi, ${user.nickname ?? user.name}`;9}10 11const asha: User = { name: "Asha", email: "asha@example.com" };12//    ^?13console.log(greet(asha));14console.log(greet({ name: "Ben" }));

Lines 1 to 5 are the interface. A User has a name and an email, both strings, and may have a nickname: the question mark on line 4 makes it optional, just as in an object type. Line 7 says greet takes a User. Line 8 uses the nickname if there is one, or the name otherwise, with ??. Line 11 makes Asha, and the query on line 12 shows const asha: User. Line 13 prints Hi, Asha.

Line 14 passes Ben with no email, and TypeScript marks it on purpose. The message has two lines:

• Argument of type '{ name: string; }' is not assignable to parameter of type 'User' means "the object you passed doesn't fit what greet asks for".
• Property 'email' is missing in type '{ name: string; }' but required in type 'User' says why: a User must have an email, and Ben's object has none.

Run it anyway and line 14 prints Hi, Ben: the function only reads names, so the missing email doesn't show yet. It would, the first time some other code sent Ben an email.

For an object, a type alias and an interface mean the same thing. TypeScript compares the shapes, so one can stand in for the other:

1type Product = { name: string; price: number };2 3interface ShopItem {4  name: string;5  price: number;6}7 8const tea: Product = { name: "Tea", price: 3 };9const sameTea: ShopItem = tea;10console.log(sameTea.price);

Line 1 names the shape with a type alias, Product. Lines 3 to 6 name the same shape with an interface, ShopItem. Line 8 makes a Product, and line 9 stores it as a ShopItem with no error, because both names describe an object with a string name and a number price. Line 10 prints 3.

Building one type on another

Often one type is another type plus a little more. An admin on a shop's account page is a user with a list of things they are allowed to do. You don't want to copy the user's properties into the admin; you want to say "an admin is a user, plus this". An interface says it with extends:

1interface User {2  name: string;3  email: string;4}5 6interface Admin extends User {7  permissions: string[];8}9 10const lee: Admin = { name: "Lee", email: "lee@example.com", permissions: ["refunds"] };11console.log(`${lee.name} can do: ${lee.permissions.join(", ")}`);

Lines 1 to 4 make User, with a name and an email. Line 6 makes Admin and says it extends User: an Admin has everything a User has. Line 7 adds what only admins have, a list of permissions (string[] is a list of strings). Line 10 makes Lee, who needs all three properties. Line 11 prints Lee can do: refunds.

A type alias can't use extends. It builds on another type with &, which means "everything in this type and everything in that one". A type made with & is called an intersection:

1type User = {2  name: string;3  email: string;4};5 6type Admin = User & {7  permissions: string[];8};9 10const lee: Admin = { name: "Lee", email: "lee@example.com", permissions: ["refunds"] };11//    ^?12console.log(`${lee.name} can do: ${lee.permissions.join(", ")}`);

Lines 1 to 4 are User as a type alias. Line 6 says an Admin is a User & the object type on lines 6 to 8, so it has a name, an email, and permissions. Line 10 makes the same Lee, the query on line 11 shows const lee: Admin, and line 12 prints the same Lee can do: refunds.

So far the two ways give the same result. They differ when the new type gets a property wrong. Below, User says a plan is "free" or "pro", and line 6 builds Admin on it. Press each button to change line 6:

1interface User {2  name: string;3  plan: "free" | "pro";4}5 6interface Admin extends User { permissions: string[] }7 8const lee: Admin = { name: "Lee", plan: "pro", permissions: ["refunds"] };9console.log(lee.name + " has " + lee.plan);

extends and & have no errors. extends, plan: number gives plan a different type from the one User has, and TypeScript marks line 6 itself: Interface 'Admin' incorrectly extends interface 'User', which means "an Admin would no longer be a User". &, plan: number gets no error on line 6. No value can be a number and "pro" at once, so Admin becomes never, a type that no value fits, and the errors appear later, on lines 8 and 9, where the type is used. With extends, the error points at the real mistake. (The Intersection types lesson covers & in depth.)

An interface can also extend more than one type, and it can extend a type alias that names an object:

1type Contact = { email: string };2 3interface Address {4  city: string;5}6 7interface Customer extends Contact, Address {8  name: string;9}10 11const asha: Customer = { name: "Asha", email: "asha@example.com", city: "Pune" };12console.log(`${asha.name} lives in ${asha.city}`);

Line 1 is a type alias, Contact, with an email. Lines 3 to 5 are an interface, Address, with a city. Line 7 says a Customer extends both, with a comma between them, and line 8 adds a name. Line 11 makes Asha with all three properties, and line 12 prints Asha lives in Pune. The two ways mix freely.

Which one to use

For most object shapes, you can use either one. A few things only one of them can do. You've seen the first: only a type alias can name a union, an exact value, or a simple type like string. The second is about declaring the same name twice. Two interfaces with the same name join into one:

1interface Settings {2  theme: string;3}4 5interface Settings {6  fontSize: number;7}8 9const settings: Settings = { theme: "dark", fontSize: 16 };10console.log(settings.fontSize);

Lines 1 to 3 make a Settings interface with a theme. Lines 5 to 7 make another one with the same name and a fontSize. TypeScript joins them, so a Settings needs both. This is called declaration merging. Line 9 makes settings with both properties, and line 10 prints 16. Libraries use merging to let you add properties to their types; a later lesson, Declaration merging, shows how.

1type Settings = { theme: string };2type Settings = { fontSize: number };

A type alias can't be declared twice. TypeScript marks both lines on purpose: Duplicate identifier 'Settings', which means "this name is already taken". An identifier is a name in your code.

The table below sums up the differences. Read each row as a question, then the answer for each keyword.

The TypeScript handbook says you can mostly choose by taste, and suggests using interface until you need something only type can do. A simple rule that follows from the table:

• Use interface for object shapes, especially ones you build on with extends, because a clash is reported where it happens.
• Use type for everything an interface can't name: unions like "free" | "pro", and other names like Email.
• Whatever you choose for objects, choose it the same way across a project, so readers aren't left wondering why.

Users and admins on an account page

Here is how the two work together on a real page. An account page shows a badge with each person's name, and adds (Pro) for pro users. Some people are admins:

1type Plan = "free" | "pro";2 3interface User {4  id: number;5  name: string;6  plan: Plan;7}8 9interface Admin extends User {10  permissions: string[];11}12 13function badge(user: User) {14  return user.plan === "pro" ? `${user.name} (Pro)` : user.name;15}16 17const asha: User = { id: 1, name: "Asha", plan: "pro" };18const lee: Admin = { id: 2, name: "Lee", plan: "free", permissions: ["refunds"] };19console.log(badge(asha));20console.log(badge(lee));

Line 1 uses a type alias for the plans, because it's a union. Lines 3 to 7 use an interface for a user, with an id, a name, and a plan. Lines 9 to 11 build Admin on User with extends. Lines 13 to 15 make the badge: line 14 adds (Pro) when the plan is "pro".

Line 17 makes Asha, a user, and line 18 makes Lee, an admin. Line 19 prints Asha (Pro). Line 20 passes Lee to badge, which asks for a User, and there's no error: an admin has everything a user has, so an admin fits wherever a user goes. It prints Lee.

Common mix-ups

Type aliases and interfaces are only for TypeScript. Neither one becomes code that runs. Here is a small file with both:

1type Plan = "free" | "pro";2 3interface User {4  name: string;5  plan: Plan;6}7 8const asha: User = { name: "Asha", plan: "pro" };9console.log(asha.plan);

Line 1 is a type alias and lines 3 to 6 are an interface. Line 8 makes a real object, and line 9 prints pro. When TypeScript turns this into JavaScript, it removes the alias, the interface, and the : User annotation:

const asha = { name: "Asha", plan: "pro" };
console.log(asha.plan);

Only the object and the log are left, and the code still prints pro. You can't use User as a value, for example with typeof or instanceof, because it doesn't exist when the code runs.

• "A type alias makes a new type." No. It's another name for the same type. Any string fits type Email = string, and hovering shows string.
• "An interface checks objects more strictly than a type alias." No. For the same shape, both check the same way, and one can stand in for the other.
• "Interfaces exist when the code runs, like classes." No. Both are removed. Nothing called User is left in profile.js.
• "A type alias can't be extended." No. & builds on it, and an interface can use extends on a type alias that names an object, as Customer did with Contact.
• "An interface can name any type." No. It always describes an object shape. For a union like "free" | "pro", use a type alias.
• "A project must use only one of them." No. They mix freely: the account page uses a type alias for the plans and interfaces for the people.

Practice exercises

Each exercise is TypeScript. When you write or fix code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

interface Product {
  name: string;
  price: number;
}

const tea: Product = { name: "Tea", price: 3 };
const cake: Product = { name: "Cake" };

1interface Product {2  name: string;3  price: number;4}5 6const tea: Product = { name: "Tea", price: 3 };7const cake: Product = { name: "Cake" }; // line 7: price is missing

1function orderLabel(order: { id: number; city: string }) {2  return `Order ${order.id} to ${order.city}`;3}4 5const first: { id: number; city: string } = { id: 7, city: "Pune" };6console.log(orderLabel(first));

1type Order = { id: number; city: string };2 3function orderLabel(order: Order) {4  return `Order ${order.id} to ${order.city}`;5}6 7const first: Order = { id: 7, city: "Pune" };8console.log(orderLabel(first));

1function greet(user: User) {2  return `Hi, ${user.name}! You have ${user.cartItems} items.`;3}4 5console.log(greet({ name: "Asha", cartItems: 2 }));

1interface User {2  name: string;3  cartItems: number;4}5 6function greet(user: User) {7  return `Hi, ${user.name}! You have ${user.cartItems} items.`;8}9 10console.log(greet({ name: "Asha", cartItems: 2 }));

1interface User {2  name: string;3  email: string;4}5 6interface Admin extends User {7  permissions: string[];8}9 10const lee: Admin = { name: "Lee", permissions: ["refunds"] };11console.log(lee.email);

1interface User {2  name: string;3  email: string;4}5 6interface Admin extends User {7  permissions: string[];8}9 10const lee: Admin = { name: "Lee", email: "lee@example.com", permissions: ["refunds"] };11console.log(lee.email);

interface Settings {
  theme: string;
}

const settings: Settings = { theme: "dark" };

interface Settings {
  fontSize: number;
}

1interface Settings {2  theme: string;3}4 5const settings: Settings = { theme: "dark", fontSize: 16 };6 7interface Settings {8  fontSize: number;9}10 11console.log(settings.fontSize);

1type Plan = "free" | "pro";2 3interface User {4  name: string;5  plan: Plan;6}7 8interface TeamUser extends User {9  plan: "team";10  seats: number;11}

1type Plan = "free" | "pro" | "team";2 3interface User {4  name: string;5  plan: Plan;6}7 8interface TeamUser extends User {9  plan: "team";10  seats: number;11}12 13const crew: TeamUser = { name: "Crew", plan: "team", seats: 5 };14console.log(`${crew.name}: ${crew.seats} seats`);

Check your understanding

For each question, ask what each name means: which properties or values it allows, and whether it's still there when the code runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A type alias, type Product = …, gives any type a name: an object, a union, or a simple type like string.
• An interface, interface User { … }, gives an object shape a name.
• Write a type once and use its name everywhere. One change is then checked at every use.
• Build on a type with interface Admin extends User or type Admin = User & { … }. extends reports a clash on the interface itself.
• Interfaces with the same name merge; type aliases with the same name are an error.
• Neither is there when the code runs, and an alias is never a new type, just a second name.

Coming next: null, undefined & strictNullChecks. It shows how TypeScript makes you handle a value that might be missing, like a user with no nickname.