Mapped types

A flag for every field of a form

A signup form has a name, an email, and an age. To show an error only after someone has left a field, the page keeps a "touched" flag for each field: true or false. You could write that type by hand, but then every new field means changing two types. A mapped type builds it from the form for you:

1type SignupForm = { name: string; email: string; age: number };2 3type Touched = { [Field in keyof SignupForm]: boolean };4//   ^?5const touched: Touched = { name: true, email: false, age: false };6console.log(touched.name);

Line 1 is the form's type. Line 3 is the mapped type. Read it as: "for each Field in the keys of SignupForm, make a property called Field whose type is boolean". The query on line 4 shows the result: { name: boolean; email: boolean; age: boolean }. Line 5 makes a touched object of that type, and line 6 prints true.

It works like a loop over an object's keys in JavaScript (the Object.keys, values, entries lesson covers Object.keys). Here is that loop, building the touched object while the page runs:

const form = { name: "Asha", email: "", age: 30 };

const touched = {};
for (const field of Object.keys(form)) {
  touched[field] = false;
}
console.log(touched);

Line 1 is a form's values. Line 4 goes through its keys, and line 5 gives each one the value false. Line 7 prints { name: false, email: false, age: false }. The mapped type does the same thing to a type, before the code runs: it goes through the keys and makes one property for each.

How [Key in keyof T] walks the keys

A mapped type has three parts. Here is one that shows each key it visits:

1type Settings = { theme: string; fontSize: number; showTips: boolean };2 3type KeyNames = { [Key in keyof Settings]: Key };4//   ^?

• keyof Settings is the union of Settings's key names: "theme" | "fontSize" | "showTips". (The keyof & typeof lesson covers keyof.)
• Key in … takes each of those names in turn. Key is a name you choose, like the variable of a for…of loop.
• The square brackets [ ] say "the property's name is Key", and the type after the colon is the property's type.

On line 3 the type after the colon is Key itself, so the query on line 4 shows each property holding its own name: { theme: "theme"; fontSize: "fontSize"; showTips: "showTips" }. Usually you want the property's type instead. Settings[Key] reads it: for "fontSize", it is number. That is an indexed access type, which the Indexed access types lesson covers.

Now try it. Type a different type after the colon on line 3, and watch the answer after ^? on line 4 and the errors on line 5. It starts as boolean, so line 5's text and number are both errors, on purpose:

1type Settings = { theme: string; fontSize: number; showTips: boolean };2 3type Saved = { [Key in keyof Settings]: boolean };4//   ^?5const saved: Saved = { theme: "dark", fontSize: 16, showTips: true };6console.log(saved.fontSize);

With Settings[Key], every property keeps its own type, so Saved is a copy of Settings and the errors are gone. Settings[Key] | null keeps each type and also allows null. string turns every property into text, so the number and the boolean on line 5 are errors.

The keys don't have to come from keyof. Any union of names works, like the names of a site's feature flags:

1type Flag = "darkMode" | "newCheckout";2 3type FlagSettings = { [Name in Flag]: boolean };4//   ^?5const flags: FlagSettings = { darkMode: true, newCheckout: false };6console.log(flags.newCheckout);

Line 1 lists the flags as a union of literal types. Line 3 maps over that union directly: Name takes "darkMode", then "newCheckout". The query on line 4 shows { darkMode: boolean; newCheckout: boolean }. Line 5 sets both, and line 6 prints false. Add a third name to line 1, and line 5 gets an error until it sets that flag too.

Adding and removing ? and readonly

A property can have two modifiers: ? makes it optional, and readonly stops code from changing it (Object types covers both). A mapped type can add them to every property at once. A profile update, where the user changes only some fields, needs every field optional:

1type Profile = { name: string; bio: string };2 3type ProfileUpdate = { [Key in keyof Profile]?: Profile[Key] };4//   ^?5const update: ProfileUpdate = { bio: "Loves green tea" };6console.log(update.bio);

Line 3 has ? after the square brackets, so every property is optional. The query on line 4 shows { name?: string | undefined; bio?: string | undefined }. TypeScript adds | undefined because reading a property that was left out gives undefined. Line 5 sends only a new bio, and line 6 prints Loves green tea.

readonly goes before the square brackets. Saved settings shouldn't change by mistake, so here every property is read-only, and line 5 is an error on purpose:

1type Settings = { theme: string; fontSize: number };2 3type FrozenSettings = { readonly [Key in keyof Settings]: Settings[Key] };4const saved: FrozenSettings = { theme: "dark", fontSize: 16 };5saved.fontSize = 18;6console.log(saved.fontSize);

Line 5 gets Cannot assign to 'fontSize' because it is a read-only property. It means the type says nobody may change fontSize after the object is made. Notice that line 6 still prints 18 if you run it: the types are removed before the code runs, so readonly doesn't freeze the object in the browser.

A minus sign takes a modifier away: -? makes every property required, and -readonly makes every property changeable. Try each one on a profile whose bio is optional:

1type Profile = { name: string; bio?: string };2 3type Changed = { [Key in keyof Profile]: Profile[Key] };4//   ^?5const update: Changed = { name: "Asha" };6update.name = "Ravi";7console.log(update.name);

Copy as it is keeps bio optional: a mapped type over keyof Profile copies the modifiers each property already had. Add ? makes name optional too. Add readonly makes line 6 an error. Remove ? makes bio required, so line 5, which has no bio, is an error. Every version prints Ravi when it runs.

Here is -readonly, turning a saved order into a draft you can edit:

1type SavedOrder = { readonly id: number; readonly total: number };2 3type OrderDraft = { -readonly [Key in keyof SavedOrder]: SavedOrder[Key] };4//   ^?5const draft: OrderDraft = { id: 7, total: 9 };6draft.total = 12;7console.log(draft.total);

Line 1's order has two read-only properties. Line 3 writes -readonly before the square brackets, and the query on line 4 shows { id: number; total: number } with no readonly left. Line 6 changes the total without an error, and line 7 prints 12.

The table below lists the five ways to write it. Read each row as: what you write, what it does, and an example.

Renaming keys with as

So far each new property kept its key's name. Add as after the keys, and you choose a new name for each one. A settings page needs a label for every setting:

1type Settings = { theme: string; fontSize: number };2 3type SettingLabels = { [Key in keyof Settings as `${Key}Label`]: string };4//   ^?5const labels: SettingLabels = { themeLabel: "Theme", fontSizeLabel: "Font size" };6console.log(labels.fontSizeLabel);

On line 3, as `${Key}Label` says what each key is called in the new type. The backticks make a template literal type: like a JavaScript template literal, but it builds a string type. For "theme" it gives "themeLabel". The next lesson, Template literal types, covers them. The query on line 4 shows { themeLabel: string; fontSizeLabel: string }. Line 5 fills in both labels, and line 6 prints Font size.

With as, the union after in doesn't even have to be key names. Here it is a union of objects, and as turns each one into a key. An app has two kinds of events, and you want one handler function for each kind, named after it:

1type ClickEvent = { kind: "click"; x: number; y: number };2type SearchEvent = { kind: "search"; query: string };3type AppEvent = ClickEvent | SearchEvent;4 5type Handlers = { [Event in AppEvent as Event["kind"]]: (event: Event) => void };6//   ^?7const handlers: Handlers = {8  click: (event) => console.log(`Clicked at ${event.x}`),9  search: (event) => console.log(`Searching for ${event.query}`),10};11handlers.search({ kind: "search", query: "tea" });

Lines 1 and 2 describe a click and a search, each with a kind. Line 3 puts them in one union (the Discriminated unions lesson uses the same pattern). On line 5, Event takes each event type in turn, and as Event["kind"] names the property after its kind. The handler's type uses the whole event. The query on line 6 shows { click: (event: ClickEvent) => void; search: (event: SearchEvent) => void }. So on line 9, TypeScript knows event has a query. Line 11 calls the search handler, which prints Searching for tea.

Leaving keys out

as can also leave a key out: if the new name is never, the type that has no values, that property isn't made. A form for a new product has no id yet, because the server gives it one. Press the buttons to change the rule on line 2:

1type Product = { id: number; name: string; price: number };2type Dropped<Key> = Key extends "id" ? never : Key;3 4type NewProduct = { [Key in keyof Product as Dropped<Key>]: Product[Key] };5//   ^?6const draft: NewProduct = { name: "Tea", price: 3 };7console.log(draft.name);

Line 2 is a conditional type: Key extends "id" ? never : Key means "if the key is "id", give never; otherwise give the key back". Line 4 runs it on each key with as Dropped<Key>. With Drop id, the query on line 5 shows { name: string; price: number }. With Keep every key, the draft on line 6 needs an id. With Drop id and price, the draft's price is one key too many. The code prints Tea every time.

The rule can look at each property's type instead of its name. A search box only searches text fields:

1type Product = { id: number; name: string; price: number; description: string };2 3type TextFields = {4  [Key in keyof Product as Product[Key] extends string ? Key : never]: Product[Key];5};6type SearchKey = keyof TextFields;7//   ^?

Line 4 keeps a key when its property's type, Product[Key], is a string, and turns it into never otherwise. id and price are numbers, so they are left out. Line 6 asks for the keys that are left, and the query on line 7 shows "name" | "description".

Typing a form's state

A real form keeps three things for its fields: the values, which fields were touched, and an error message for each field. Two mapped types make the last two from the form's type, so the form's fields are written in one place. Press the buttons to change the form on line 1:

1type SignupForm = { name: string; email: string; age: number };2 3type FormErrors<Form> = { [Field in keyof Form]?: string };4type FormTouched<Form> = { [Field in keyof Form]: boolean };5 6const values: SignupForm = { name: "Asha", email: "", age: 30 };7const touched: FormTouched<SignupForm> = { name: true, email: true, age: false };8const errors: FormErrors<SignupForm> = {};9 10if (touched.email && values.email === "") {11  errors.email = "Enter your email";12}13console.log(errors.email);

Line 3 gives every field an optional error message, and line 4 gives every field a boolean. Both take the form as a type parameter, Form, so they work for any form (Generic types & interfaces covers types with type parameters). Lines 6 to 8 are the form's state. Line 10 checks whether the email was touched and is still empty, and line 11 stores a message. Line 13 prints Enter your email.

With Add a phone field, both values and touched need a phone, and TypeScript points at lines 6 and 7. With Rename email to mail, every line that still says email gets an error, with the fix in the message. Without mapped types, you would have three types to keep in step by hand.

Common mix-ups

readonly from a mapped type only covers the top level. A nested object can still change:

1type Settings = { theme: string; layout: { sidebar: boolean } };2type FrozenSettings = { readonly [Key in keyof Settings]: Settings[Key] };3 4const settings: FrozenSettings = { theme: "dark", layout: { sidebar: true } };5settings.layout.sidebar = false;6console.log(settings.layout.sidebar);

Line 2 makes theme and layout read-only. Line 5 doesn't replace layout; it changes a property inside it, and that inner sidebar isn't read-only. So there is no error, and line 6 prints false. Making every level read-only needs a mapped type that calls itself, which the Writing your own utility types lesson builds.

A mapped type is also different from an index signature. Here are both, with a misspelled key, an error on purpose:

1type Settings = { theme: string; fontSize: number };2 3type AnyFlags = { [key: string]: boolean };4type SettingFlags = { [Key in keyof Settings]: boolean };5 6const loose: AnyFlags = { theme: true, colour: true };7const exact: SettingFlags = { theme: true, colour: true };

Line 3 is an index signature: any text key may hold a boolean, so line 6's colour is fine. Line 4 is a mapped type with exactly the keys of Settings. Line 7 gets Object literal may only specify known properties, and 'colour' does not exist in type 'SettingFlags': the key is misspelled. fontSize is missing too, but TypeScript reports only the extra key here.

• "A mapped type copies my object while the page runs." No. It builds a type, before the code runs. To build an object, you still write code, like the loop in the overview.
• "readonly in a mapped type freezes the object." No. It only makes changing it a type error. The frozen settings example still prints 18 when it runs.
• "readonly reaches every level." No. It covers the properties of the top object only.
• "Copying a type with [Key in keyof T] drops its ?." No. A mapped type over keyof T keeps each property's ? and readonly. Use -? or -readonly to take them away.
• "A key that maps to never stays, with the type never." No. With as, a key that becomes never is left out. A property whose type is never, after the colon, would stay.
• "I have to write these myself every time." No. TypeScript has Partial, Required, Readonly, Pick, Omit, and Record built in, and they are built from mapped types. The Partial, Pick, Omit & friends lesson covers them.

The table below compares the two from the example above. Read each row as a question, then the mapped type's answer, then the index signature's.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code: the errors update as you type, and a // ^? line under a type name shows what TypeScript made. Try a guess first, then use the hints.

1type Settings = { theme: string; fontSize: number; showTips: boolean };2 3type AsText = { [Key in keyof Settings]: string };4type FontSize = AsText["fontSize"];

1type Settings = { theme: string; fontSize: number; showTips: boolean };2 3type AsText = { [Key in keyof Settings]: string };4type FontSize = AsText["fontSize"];5//   ^?

1type Profile = { name: string; bio?: string; age: number };2 3type Copy = { [Key in keyof Profile]: Profile[Key] };

1type Profile = { name: string; bio?: string; age: number };2 3type Copy = { [Key in keyof Profile]: Profile[Key] };4//   ^?

1type CheckoutForm = { address: string; card: string };2type Touched<Form> = unknown;3 4const touched: Touched<CheckoutForm> = { address: true, card: false };5console.log(touched.address);

1type CheckoutForm = { address: string; card: string };2type Touched<Form> = { [Field in keyof Form]: boolean };3 4const touched: Touched<CheckoutForm> = { address: true, card: false };5console.log(touched.address);

1type Profile = { name: string; bio: string };2type Nullable<T> = T;3 4const profile: Nullable<Profile> = { name: "Asha", bio: null };5console.log(profile.bio);

1type Profile = { name: string; bio: string };2type Nullable<T> = { [Key in keyof T]: T[Key] | null };3 4const profile: Nullable<Profile> = { name: "Asha", bio: null };5type Bio = Nullable<Profile>["bio"];6//   ^?7console.log(profile.bio);

1type SignupForm = { name: string; email: string };2 3type SignupErrors = { [Field in keyof SignupForm]?: string };4const errors: SignupErrors = { emailError: "Enter your email" };5console.log(errors.emailError);

1type SignupForm = { name: string; email: string };2 3type SignupErrors = { [Field in keyof SignupForm as `${Field}Error`]?: string };4//   ^?5const errors: SignupErrors = { emailError: "Enter your email" };6console.log(errors.emailError);

1type Cart = { items: string[]; total: number; checkout: () => void; clear: () => void };2 3type DataOnly = { [Key in keyof Cart]: Cart[Key] };4const saved: DataOnly = { items: ["Tea"], total: 3 };5console.log(saved.total);

1type Cart = { items: string[]; total: number; checkout: () => void; clear: () => void };2type NotAFunction<Key, Value> = Value extends (...args: any[]) => any ? never : Key;3 4type DataOnly = { [Key in keyof Cart as NotAFunction<Key, Cart[Key]>]: Cart[Key] };5//   ^?6const saved: DataOnly = { items: ["Tea"], total: 3 };7console.log(saved.total);

Check your understanding

For each question, go through the keys one at a time: what is the new key called, is it left out, and what type and modifiers does it get? The quiz code isn't checked on the page, so no error list or type hint gives the answer away.

Key takeaways

• { [Key in keyof T]: … } goes through every key of T and makes one property for each.
• The type after the colon is each property's type. T[Key] keeps the original type.
• ? and readonly add modifiers to every property; -? and -readonly take them away. A plain copy keeps the ones it had.
• as gives each key a new name. A key that becomes never is left out.
• Mapped types only change types. They don't copy, freeze, or check objects while the page runs.
• Build related types from one source type, and they all follow it when it changes.

Coming next: Template literal types. They build string types from other types, like the themeLabel keys in this lesson, and event names like onClick.