Object types

Say what an object must hold

A shop page shows a label for each product, like Tea: $3. A small function builds it from a product object with a name and a price. Here it is in plain JavaScript, called once with a whole product and once with a product that has no price:

function productLabel(product) {
  return `${product.name}: $${product.price}`;
}
console.log(productLabel({ name: "Tea", price: 3 }));
console.log(productLabel({ name: "Cake" }));

Line 1 makes productLabel, which takes one product. Line 2 builds the label from its name and price with a template literal. Line 4 prints Tea: $3. Line 5 passes a cake with no price, and prints Cake: $undefined. Reading a property an object doesn't have gives undefined (the Object basics lesson covers this), and nothing warns you.

In TypeScript you can say which properties the product must have, and what type each one is. That description is called an object type. Here is the same code with one added:

1function productLabel(product: { name: string; price: number }) {2  return `${product.name}: $${product.price}`;3}4console.log(productLabel({ name: "Tea", price: 3 }));5console.log(productLabel({ name: "Cake" }));

The only change is on line 1: product: { name: string; price: number }. Read it as "product is an object with a name that is a string and a price that is a number". Line 4 passes such an object, so it's fine. Line 5 passes a cake with no price, and TypeScript marks it on purpose, because it's the bug. The message has two lines:

• Argument of type '{ name: string; }' is not assignable to parameter of type '{ name: string; price: number; }' means "the object you passed doesn't fit what the function asks for". An argument is a value you pass in a call. A parameter is the name that receives it, here product.
• Property 'price' is missing in type '{ name: string; }' says why: the object has no price, and the type needs one.

Notice how TypeScript writes the type of what you passed: { name: string; }. It describes every object the same way, as a list of property names and their types. Try it: type a different object for line 4, and watch the list under the code.

1function productLabel(product: { name: string; price: number }) {2  return `${product.name}: $${product.price}`;3}4console.log(productLabel({ name: "Cake" }));

With { name: "Cake", price: 4 }, every property is there with the right type, and the error is gone. The order of the properties doesn't matter. A price in quotes is text, so it gets Type 'string' is not assignable to type 'number'. An empty {} is missing both properties, and leaving the box empty passes no object at all. An extra property, like colour: "green", gets an error too: Object literal may only specify known properties. The Excess property checks lesson explains when TypeScript checks for extras.

Writing an object type

You can write an object type anywhere a type goes. After a function parameter, as in the overview, is the most common place. After a variable name works the same way, and the type stays with the variable:

1let product: { name: string; price: number } = { name: "Tea", price: 3 };2product = { name: "Cake", price: 4 };3product.price = "5";4console.log(product.price);

Line 1 says product must always hold an object with a string name and a number price, and gives it the tea. Line 2 puts a different object in it, a cake, which has the same shape, so it's fine. Line 3 changes just the price to the text "5". TypeScript marks it on purpose: Type 'string' is not assignable to type 'number', "you're putting text where a number has to go". Run it anyway, and line 4 prints 5: the text, which would break any sum later.

A few rules about how you write the type itself:

• Each property is a name, a colon, and a type: price: number.
• Properties are separated by semicolons, commas, or new lines. { name: string, price: number } means the same.
• The order of the properties doesn't matter, in the type or in the object.
• A long type can spread over several lines, one property per line.

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

Lines 1 to 4 are the parameter order and its type: an id that is a number on line 2, and a city that is a string on line 3. Line 5 builds the label. Line 7 passes the city first and the id second, and there's no error. It prints Order 7 to Pune.

You don't always write the type. When a variable starts with an object, TypeScript works out its type from the object. This is inference, from the Type annotations & inference lesson:

1const product = { name: "Tea", price: 3, inStock: true };2//    ^?3console.log(product.colour);

Line 1 makes a product with three properties and no type written. The // ^? comment on line 2 asks TypeScript for the type of the name its ^ points at, and the page writes the answer after it: an object type with name: string, price: number, and inStock: boolean (a boolean is true or false). Line 3 asks for product.colour, which isn't in that type. TypeScript marks it on purpose: Property 'colour' does not exist on type …. In plain JavaScript it would print undefined.

So TypeScript knows an object's shape whether you write it or not. You write object types where there's no value to work them out from, which is mostly function parameters: a function can't know what callers will pass.

Properties that can be left out

Some properties are often missing. A user profile always has a name, but not every user picks a nickname. Put a question mark after the name of a property, nickname?: string, and the property becomes optional: an object may leave it out. If it's there, it must be a string.

1const user: { name: string; nickname?: string } = { name: "Asha" };2const nickname = user.nickname;3//    ^?4console.log(nickname);

Line 1 makes Asha's profile with only a name, which is fine because nickname is optional. Line 2 reads the nickname. The query on line 3 shows its type: string | undefined. The | means "or": the nickname is a string or undefined, because the property may not be there. Line 4 prints undefined. (The Union types lesson covers | in full.)

Because the nickname may be undefined, TypeScript won't let you use it as a string until you've handled that case. Try four ways to turn a user into a display name. Asha has no nickname; Ben's is Benji:

1function displayName(user: { name: string; nickname?: string }) {2  return user.nickname.toUpperCase();3}4console.log(displayName({ name: "Asha" }));5console.log(displayName({ name: "Ben", nickname: "Benji" }));

Use it directly gets 'user.nickname' is possibly 'undefined', which means "this might be undefined, and you can't call a method on undefined". Run it, and Asha's call throws a TypeError. The other three handle the missing nickname, so the error goes away: Check it first with ? :, Fall back with ?? to the name, or use optional chaining ?., which gives undefined instead of throwing. The Nullish coalescing and optional chaining lesson explains ?? and ?..

A question mark isn't the same as writing | undefined in the type yourself. Compare three profiles:

1const asha: { name: string; nickname?: string } = { name: "Asha" };2const ben: { name: string; nickname: string | undefined } = { name: "Ben" };3const chen: { name: string; nickname: string | undefined } = { name: "Chen", nickname: undefined };

Line 1 uses nickname?, so Asha can leave it out. Line 2 says nickname: string | undefined with no question mark. The value may be undefined, but the property must be written, so TypeScript marks line 2 on purpose: Property 'nickname' is missing in type '{ name: string; }'. Line 3 writes nickname: undefined, and that's fine.

The table below compares the two. Read each row as a question, then the answer for each way of writing the type.

Read-only properties

Some properties should never change once an object exists, like an order's id. Write readonly before the property, and TypeScript reports any line that assigns to it:

1const order: { readonly id: number; total: number } = { id: 7, total: 10 };2order.total = 12;3order.id = 8;4console.log(order.id, order.total);

Line 1 says the order has a read-only id and a total you can change, and makes order 7 with a total of 10. Line 2 changes the total to 12, which is fine. Line 3 tries to change the id, and TypeScript marks it on purpose: Cannot assign to 'id' because it is a read-only property. "Assign" means "store a new value with =".

Now run it. Line 4 prints 8 12: the id really changed. readonly is a TypeScript check, like every type. It's removed with the other types before the code runs, so nothing stops the change in the browser.

That's still useful. It catches the mistake while you write, which is when you want to hear about it. If you also need the object locked while the code runs, JavaScript has Object.freeze (the Immutability lesson covers it).

You've now seen three ways to write a property. The table below compares them. Read each row as one way of writing a property, then what it allows.

Objects inside objects

A property can hold another object. An order has a shipping address, and the address has a city and a zip code. The type of that property is an object type too, written inside the outer one:

1const order: {2  id: number;3  shipTo: { city: string; zip: string };4} = {5  id: 7,6  shipTo: { city: "Pune", zip: "411001" },7};8const shipTo = order.shipTo;9//    ^?10console.log(order.shipTo.city);

Lines 1 to 4 hold the type. Line 2 says the order has a number id. Line 3 says it has a shipTo, and that shipTo is itself an object with a city and a zip, both strings. Lines 4 to 7 make the order, with the inner object on line 6. Line 8 reads order.shipTo, and the query on line 9 shows its type: the inner object type from line 3. Line 10 reads two levels deep and prints Pune.

TypeScript checks every level. Change what line 6 puts in shipTo, and watch where the error lands:

1const order: {2  id: number;3  shipTo: { city: string; zip: string };4} = {5  id: 7,6  shipTo: { city: "Pune", zip: "411001" },7};8console.log(`Ship to ${order.shipTo.city}, ${order.shipTo.zip}`);

The error lands on line 6, inside the order, at the exact property that's wrong. A zip as a number is the sneaky one: the label looks right, so plain JavaScript would never tell you. A whole address written as one string gets an error that quotes the inner type.

readonly works one level at a time. A read-only property that holds an object stops you from replacing the object, but not from changing what's inside it:

1const order: {2  readonly id: number;3  readonly shipTo: { city: string };4} = { id: 7, shipTo: { city: "Pune" } };5 6order.shipTo.city = "Goa";7order.shipTo = { city: "Delhi" };8console.log(order.shipTo.city);

Lines 1 to 4 make an order whose shipTo is read-only. Line 6 changes the city inside it to Goa, and TypeScript allows it: city itself isn't read-only. Line 7 replaces the whole address, and TypeScript marks it on purpose: Cannot assign to 'shipTo' because it is a read-only property. Run it anyway, and line 8 prints Delhi, because line 7 still runs. To lock the city too, write readonly on city as well.

An inner object can be optional too. Then you have to check that it's there before you read inside it:

1function shippingCity(order: { id: number; shipTo?: { city: string } }) {2  return order.shipTo.city;3}4console.log(shippingCity({ id: 7 }));

Line 1 says shipTo is optional, with the question mark. Line 2 reads order.shipTo.city without checking. TypeScript marks it on purpose: 'order.shipTo' is possibly 'undefined'. Line 4 passes an order with no address, and when it runs, reading city of undefined throws a TypeError. Here is the fix:

1function shippingCity(order: { id: number; shipTo?: { city: string } }) {2  return order.shipTo?.city ?? "No address yet";3}4console.log(shippingCity({ id: 7 }));5console.log(shippingCity({ id: 8, shipTo: { city: "Pune" } }));

Line 2 uses ?., which stops and gives undefined when shipTo is missing, and ??, which then gives "No address yet" instead. Line 4 prints No address yet. Line 5 passes an order with an address and prints Pune.

A profile card on an account page

An account page shows a card for the signed-in user. The user object comes with an id that must never change, a name, a picture the user may not have uploaded, and an address. One parameter type describes all of it:

1function profileCard(user: {2  readonly id: number;3  name: string;4  avatarUrl?: string;5  address: { city: string; country: string };6}) {7  const avatar = user.avatarUrl ?? "default-avatar.png";8  return `${user.name} from ${user.address.city} (${avatar})`;9}10 11console.log(profileCard({12  id: 1,13  name: "Asha",14  address: { city: "Pune", country: "India" },15}));

Lines 1 to 6 are the function and its parameter's type:

• Line 2: readonly id, because a user's id never changes.
• Line 3: a name that every user has.
• Line 4: avatarUrl?, a picture address that may be missing.
• Line 5: an address object inside the user, with a city and a country.

Line 7 falls back to a default picture with ??, because avatarUrl may be undefined. Line 8 reads the city two levels deep. Lines 11 to 15 call the function with Asha, who has no picture, and print Asha from Pune (default-avatar.png). Press Edit & run and try removing the address, or reading user.avatarUrl.length: each gets an error from this lesson.

Common mix-ups

One mix-up comes from JavaScript itself. When a function takes an object, you often unpack its properties right in the brackets, which is called destructuring. It looks natural to add the types there:

1function productLabel({ name: string, price: number }) {2  return `${string}: $${number}`;3}4console.log(productLabel({ name: "Tea", price: 3 }));

In destructuring, name: string already means something in JavaScript: "take the property name and store it in a variable called string". So line 1 makes two variables named string and number, and line 2 uses them. TypeScript marks line 1 twice on purpose: Binding element 'string' implicitly has an 'any' type, which means "nothing says what type this variable is" (any is the next lesson's topic). It still prints Tea: $3. The fix puts the object type after the whole pattern:

1function productLabel({ name, price }: { name: string; price: number }) {2  return `${name}: $${price}`;3}4console.log(productLabel({ name: "Tea", price: 3 }));

Line 1 unpacks name and price, then gives the whole object its type after the closing brace. No errors, and line 4 prints Tea: $3.

Another mix-up: const doesn't make an object's properties read-only.

1const cart = { total: 3 };2cart.total = 5;3console.log(cart.total);

Line 1 makes a const cart. Line 2 changes its total, and TypeScript reports nothing. Line 3 prints 5. const means the name cart always points at this object; the object itself can change (the Objects and references lesson explains why).

• "The properties must be in the same order as the type." No. Order never matters, only names and types.
• "nickname?: string is the same as nickname: string | undefined." No. With ?, the property can be left out. With | undefined, it must be written, even as undefined.
• "readonly stops the change while the code runs." No. It's removed with the other types. The order example still printed 8 12. Use Object.freeze for that.
• "A read-only object can't change anywhere inside." No. readonly covers one property. The city inside a read-only shipTo still changed to Goa.
• "const makes the properties read-only." No. It only stops the name from pointing at a different object.
• "I have to write a type for every object." No. TypeScript works out the type of an object you store in a variable. Write object types mostly for function parameters.

The table below compares three ways to stop changes. Read each row as one thing you can write, then what it stops, and when.

Practice exercises

Each exercise is TypeScript. When you 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.

const settings: { theme: string; fontSize: number; showTips: boolean } = {
  theme: "dark",
  fontSize: 16,
};

1const settings: { theme: string; fontSize: number; showTips: boolean } = {2  theme: "dark",3  fontSize: 16,4  showTips: true,5};

1const settings: { theme: string; fontSize?: number } = { theme: "dark" };2const size = settings.fontSize;

1const settings: { theme: string; fontSize?: number } = { theme: "dark" };2const size = settings.fontSize;3//    ^?

1function todoLabel(todo: { title: string }) {2  return (todo.done ? "[x] " : "[ ] ") + todo.title;3}4 5const todo = { title: "Buy tea", done: true };6console.log(todoLabel(todo));

1function todoLabel(todo: { title: string; done: boolean }) {2  return (todo.done ? "[x] " : "[ ] ") + todo.title;3}4 5const todo = { title: "Buy tea", done: true };6console.log(todoLabel(todo));

1function fontSizeOf(settings: { theme: string; fontSize: number }) {2  return settings.fontSize;3}4console.log(fontSizeOf({ theme: "dark" }));

1function fontSizeOf(settings: { theme: string; fontSize?: number }) {2  return settings.fontSize ?? 16;3}4console.log(fontSizeOf({ theme: "dark" }));

1const order: {2  readonly id: number;3  readonly shipTo: { city: string };4} = { id: 7, shipTo: { city: "Pune" } };5 6order.shipTo.city = "Goa";7console.log(order.shipTo.city);

1const order: {2  readonly id: number;3  readonly shipTo: { readonly city: string };4} = { id: 7, shipTo: { city: "Pune" } };5 6order.shipTo.city = "Goa";7console.log(order.shipTo.city);

1function describeSettings(settings: { theme: string }) {2  const sound = settings.alerts.sound ? "on" : "off";3  return `${settings.theme} theme, sound ${sound}`;4}5 6const settings = { theme: "dark", alerts: { sound: false, email: true } };7console.log(describeSettings(settings));

1function describeSettings(settings: {2  theme: string;3  alerts: { sound: boolean; email: boolean };4}) {5  const sound = settings.alerts.sound ? "on" : "off";6  return `${settings.theme} theme, sound ${sound}`;7}8 9const settings = { theme: "dark", alerts: { sound: false, email: true } };10console.log(describeSettings(settings));

Check your understanding

For each question, keep two moments apart: what TypeScript says before the code runs, and what the code does when it runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• An object type lists an object's properties and the type of each: { name: string; price: number }.
• TypeScript reports a missing property, a property with the wrong type, and reading a property the type doesn't have.
• Order doesn't matter. Separate properties with semicolons, commas, or new lines.
• nickname?: string can be left out, and reading it gives string | undefined, so handle the missing case with a check, ??, or ?..
• readonly id: number makes TypeScript report any change to id. It covers one level, and it's gone when the code runs.
• A property's type can be another object type, and TypeScript checks every level.

Coming next: any, unknown & never. It covers the type that turns checking off, the safe type for values you don't know yet, and the type that has no values at all.