Template literal types

A string type with a pattern

A shop's buttons get their look from CSS classes. There are two sizes, so there are two classes: btn-small and btn-large. Any other class name, like a typo, gives a button with no style at all. You already know how to list the sizes as a union of literal types. Now you can build the class names from them:

1type Size = "small" | "large";2type ButtonClass = `btn-${Size}`;3//   ^?4const saveButton: ButtonClass = "btn-smal";5console.log(saveButton);

Line 1 says a Size is the text "small" or the text "large". Line 2 is the new part. It looks like a JavaScript template literal, with backticks and a ${ } placeholder, but it's a type. It means "the text btn-, followed by a Size". This is called a template literal type. The Mapped types lesson used one to rename keys, `${Key}Label`; this lesson shows what they can do.

The query on line 3 shows what TypeScript made of it: "btn-small" | "btn-large", exactly two strings. Line 4 stores "btn-smal", with an l missing. TypeScript marks it, on purpose here, because it's the bug:

• Type '"btn-smal"' is not assignable to type '"btn-small" | "btn-large"' means "this text isn't one of the two class names". "Assignable" means "allowed to be stored there".
• Did you mean '"btn-small"'? is TypeScript's guess at the fix, because the text is very close to one of the names. This version of the error has the number ts(2820).

Line 5 still prints btn-smal when it runs: the type is a check before the code runs, not a change to it. Now type your own class name for line 4 and watch the list under the code:

1type Size = "small" | "large";2type ButtonClass = `btn-${Size}`;3//   ^?4const saveButton: ButtonClass = "btn-smal";5console.log(saveButton);

"btn-small" and "btn-large" have no errors. "btn-medium" gets one, because medium isn't a size. "BTN-SMALL" gets one too: capital letters make a different string. And "small" is missing the fixed text btn- that every name starts with.

Template types look like template literals

Here is the same idea as plain JavaScript, with a value instead of a type:

const size = "small";
const className = `btn-${size}`;
console.log(className);

Line 1 stores the text "small". Line 2 puts the value of size into the placeholder while the code runs. Line 3 prints btn-small: one string. A template literal type uses the same backticks, but its placeholder holds a type, and the result is a type: every string that fits.

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

The placeholder doesn't have to hold a union. It can hold number, which makes a pattern for CSS sizes:

1type Pixels = `${number}px`;2 3const width: Pixels = "120px";4const gap: Pixels = "1.5px";5const height: Pixels = "tall";6const margin: Pixels = 120;

Line 1 says a Pixels value is text that reads as a number, followed by px. Lines 3 and 4 fit: 120 and 1.5 both read as numbers. TypeScript marks two lines on purpose:

• Line 5, "tall": Type '"tall"' is not assignable to type '`${number}px`'. The text tall doesn't read as a number.
• Line 6, 120: Type '120' is not assignable to the same type. A template literal type is always a string type, and 120 without quotes is a number, not text.

A string placeholder takes any text at all. User IDs that must start with user- look like this:

1type UserId = `user-${string}`;2 3const asha: UserId = "user-asha";4const sam: UserId = "user-42";5const guest: UserId = "guest-7";

Line 1 says a UserId is user- followed by any text. Lines 3 and 4 fit, whatever comes after the dash. Line 5 starts with guest-, so TypeScript marks it on purpose: the fixed text has to be there exactly.

The table below lists what each kind of placeholder lets in. Read each row as: this type in the placeholder, then which strings fit.

A union fills in every combination

A pattern can have more than one placeholder. A toast is a small message that pops up in a corner of the page, like "Saved". Its position is a side and an alignment:

1type Side = "top" | "bottom";2type Align = "left" | "right";3type ToastPosition = `${Side}-${Align}`;4//   ^?5const toast: ToastPosition = "bottom-right";6console.log(toast);

Line 1 lists two sides and line 2 two alignments. Line 3 joins a side, a dash, and an alignment. The query on line 4 shows that TypeScript made every combination: "top-left", "top-right", "bottom-left", and "bottom-right". Line 5 picks one of them, and line 6 prints bottom-right.

Change the sides on line 1, and watch the answer after the query on line 4:

1type Side = "top" | "bottom";2type Align = "left" | "right";3type ToastPosition = `${Side}-${Align}`;4//   ^?5const toast: ToastPosition = "bottom-right";6console.log(toast);

With Only top, there are 2 names, and line 5's "bottom-right" isn't one of them. With Add center, there are 6: the count is always the number of sides times the number of alignments. Each union you add multiplies again, so the count grows fast. TypeScript refuses a pattern that would make 100,000 names or more:

1type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";2type PostalCode = `${Digit}${Digit}${Digit}${Digit}${Digit}`;

Line 1 lists the ten digits. Line 2 asks for five of them in a row, like a five-digit postal code. That is 10 × 10 × 10 × 10 × 10, which is 100,000 names, so TypeScript marks line 2 on purpose: Expression produces a union type that is too complex to represent. For a part that can be almost anything, put string or number in the placeholder instead of a long union.

Uppercase, Lowercase, and Capitalize

Names in code often need a capital letter where the data has none. React components, for example, take handler props like onClick for the click event. TypeScript has four built-in helpers that change the case of a string type. You write the helper's name and then a string type in angle brackets, the way you pass a type to a generic:

1type Loud = Uppercase<"save">;2//   ^?3type Quiet = Lowercase<"SAVE">;4//   ^?5type Title = Capitalize<"save">;6//   ^?7type Plain = Uncapitalize<"Save">;8//   ^?

Line 1 turns "save" into "SAVE", as the query on line 2 shows. Line 3 does the opposite. Line 5 changes only the first letter, so the query on line 6 shows "Save", and line 7 makes the first letter small again.

The table below sums them up. Read each row as: this helper, what it does, and an example.

The helpers work inside a pattern, too. Here line 2 builds handler names from a button's events. Pick a different helper and watch whether line 4's "onClick" still fits:

1type ButtonEvent = "click" | "focus";2type HandlerName = `on${Capitalize<ButtonEvent>}`;3//   ^?4const handler: HandlerName = "onClick";5console.log(handler);

Only Capitalize makes "onClick". Uppercase makes "onCLICK", and Lowercase or no helper leaves "onclick". Strings are case-sensitive, so each of those is a different name, and line 4 gets an error.

The helpers change types. They don't know about the string methods you call while the code runs:

1const loud = "save".toUpperCase();2//    ^?3console.log(loud);

Line 1 calls .toUpperCase() on "save", and line 3 prints SAVE. But the query on line 2 shows const loud: string, not "SAVE". TypeScript knows the method gives back some string. It doesn't work out which one.

Typed event names

A profile page lets a user change their name, email, and age, and other parts of the page listen for those changes. The events are called nameChanged, emailChanged, and ageChanged. You could list them by hand, but then a new property needs a new event name too. Build them from the object type instead:

1type Profile = { name: string; email: string; age: number };2type ProfileEvent = `${keyof Profile}Changed`;3//   ^?4 5function on(event: ProfileEvent, handler: () => void) {6  console.log(`Listening for ${event}`);7}8 9on("nameChanged", () => {});10on("name", () => {});

Line 1 describes a profile. On line 2, keyof Profile means "the names of Profile's properties", the union "name" | "email" | "age". The pattern adds Changed to each, and the query on line 3 shows the three event names. Lines 5 to 7 make an on function that takes one of them. This one only prints what it listens for; a real one would save the handler and call it later.

Line 9 passes "nameChanged", which fits. Line 10 passes the property name "name", a common slip, and TypeScript marks it on purpose: Argument of type '"name"' is not assignable to parameter of type '"nameChanged" | "emailChanged" | "ageChanged"'. An argument is a value you pass to a function, and a parameter is the name that receives it. The code still prints both lines when it runs.

The handler doesn't know what changed yet: a new age is a number, but a new name is text. TypeScript can work that out from the event name. This uses a type parameter K with a keyof constraint, as in the Generic constraints lesson:

1type Profile = { name: string; email: string; age: number };2 3function on<K extends keyof Profile>(4  event: `${K}Changed`,5  handler: (value: Profile[K]) => void,6) {7  console.log(`Listening for ${event}`);8}9 10on("ageChanged", (value) => console.log(value));11//                ^?

Line 3 says K must be one of Profile's property names. Line 4 says the event is K followed by Changed. Line 5 says the handler gets a value of type Profile[K], the type of the property that K names. Line 10 passes "ageChanged". TypeScript asks which K makes `${K}Changed` equal "ageChanged", and finds "age". So the query on line 11 shows (parameter) value: number. When it runs, line 7 prints Listening for ageChanged.

Pass a different event name on line 10 and watch the type of value:

1type Profile = { name: string; email: string; age: number };2 3function on<K extends keyof Profile>(4  event: `${K}Changed`,5  handler: (value: Profile[K]) => void,6) {7  console.log(`Listening for ${event}`);8}9 10on("ageChanged", (value) => console.log(value));11//                ^?

"nameChanged" and "emailChanged" give a string. "age" and "ageChange" don't fit the pattern, so line 10 gets an error, and TypeScript can only say value is string | number.

Analytics events and handler names

Shops record what shoppers do, like opening the cart, in an analytics tool. The names have to be exactly right, or the reports miss them. A pattern keeps them right:

1type Area = "cart" | "checkout";2type Action = "open" | "close";3type AnalyticsEvent = `${Area}:${Action}`;4 5function track(event: AnalyticsEvent) {6  console.log(`Tracked ${event}`);7}8 9track("cart:open");10track("checkout:close");11track("cart:opne");

Lines 1 and 2 list the areas and the actions. Line 3 joins them with a colon, which makes four names, from "cart:open" to "checkout:close". Lines 5 to 7 make a track function that takes only those names. Lines 9 and 10 pass real names. Line 11 has two letters swapped, "cart:opne", and TypeScript marks it on purpose. Without the type, this typo would print Tracked cart:opne and send a name nobody looks for.

Sometimes your code builds the name while it runs, such as a handler name from an event. As you saw, string methods give back only string. When you're sure what the code makes, you can tell TypeScript with as:

1type FormEvent = "submit" | "reset";2 3function handlerName<E extends FormEvent>(event: E) {4  const name = `on${event[0].toUpperCase()}${event.slice(1)}`;5  return name as `on${Capitalize<E>}`;6}7 8const submitHandler = handlerName("submit");9//    ^?10console.log(submitHandler);

Line 3 makes a function for one form event, E. Line 4 builds the name: on, the first letter in capitals, then the rest of the event. Line 5 says "this string is `on${Capitalize<E>}`". TypeScript trusts you here, so line 4 must really do what the type says. Line 8 calls it with "submit", the query on line 9 shows the exact type "onSubmit", and line 10 prints onSubmit.

Common mix-ups

A template literal type checks strings that TypeScript can see in your code. Text that arrives while the page runs is different. Here a shopper types a width into a box:

1type Pixels = `${number}px`;2 3const widthInput = document.createElement("input");4widthInput.value = "120px";5 6const width: Pixels = widthInput.value;7console.log(width);

Line 3 makes an <input> text box, and line 4 puts 120px in it, as if the shopper typed it. Line 6 stores the box's value as Pixels, and TypeScript marks it on purpose: Type 'string' is not assignable to type '`${number}px`'. A text box can hold any text, so TypeScript only knows the value is a string. It can't know the shopper typed something that fits. The fix is to check the text while the code runs:

1type Pixels = `${number}px`;2 3function isPixels(text: string): text is Pixels {4  return /^\d+(\.\d+)?px$/.test(text);5}6 7const widthInput = document.createElement("input");8widthInput.value = "120px";9 10const text = widthInput.value;11if (isPixels(text)) {12  const width: Pixels = text;13  console.log(width);14}

Lines 3 to 5 make isPixels, a type guard. Line 4 tests the text with a regular expression: digits, maybe a decimal part, then px. Its return type, text is Pixels, tells TypeScript that a true answer means the text fits. So inside the if on line 11, line 12 can store it as Pixels, and line 13 prints 120px.

The table below lists where text comes from. Read each row as: text from here, then what TypeScript knows about it.

• "A template literal type makes a string." No. It describes which strings are allowed. Your code still writes or builds every string, and the type is gone when the code runs.
• "TypeScript checks what users type against the pattern." No. Text from an input or a server is only a string to TypeScript. Check it with your own code, like isPixels.
• "Uppercase changes my values." No. It changes types. To change a value, call .toUpperCase(), whose type is just string.
• "Two unions in a pattern add up." No. They multiply: 2 sides and 3 alignments make 6 names, not 5.
• "`${number}px` takes the number 120." No. It takes text, like "120px". Every template literal type is a string type.
• "Case doesn't matter in a pattern." No. "onclick" and "onClick" are different strings, which is why the case helpers exist.

Practice exercises

Each exercise is TypeScript. To change the starter code, press Edit & run: the errors update as you type, and a // ^? line under a type shows TypeScript's answer. Try a guess first, then use the hints.

1type Lang = "en" | "fr";2type GreetingKey = `greeting-${Lang}`;

1type Lang = "en" | "fr";2type GreetingKey = `greeting-${Lang}`;3//   ^?

type Theme = "light" | "dark";
type ThemeClass = `theme-${Theme}`;

const page: ThemeClass = "theme-dark";
const card: ThemeClass = "dark-theme";

1type Theme = "light" | "dark";2type ThemeClass = `theme-${Theme}`;3 4const page: ThemeClass = "theme-dark";5const card: ThemeClass = "theme-light";

1type Size = string;2 3const gap: Size = "8px";4const padding: Size = "1.5rem";5const margin: Size = "large";

1type Size = `${number}px` | `${number}rem`;2 3const gap: Size = "8px";4const padding: Size = "1.5rem";5const margin: Size = "large";

1type ModalEvent = "open" | "close";2type ModalHandler = `on${ModalEvent}`;3 4const handler: ModalHandler = "onOpen";5console.log(handler);

1type ModalEvent = "open" | "close";2type ModalHandler = `on${Capitalize<ModalEvent>}`;3 4const handler: ModalHandler = "onOpen";5console.log(handler);

1type Cart = { items: number; total: number };2type CartEvent = `${keyof Cart}Updated`;3 4function on(event: CartEvent, handler: () => void) {5  console.log(`Listening for ${event}`);6}7 8on("totalUpdate", () => {});

1type Cart = { items: number; total: number };2type CartEvent = `${keyof Cart}Updated`;3 4function on(event: CartEvent, handler: () => void) {5  console.log(`Listening for ${event}`);6}7 8on("totalUpdated", () => {});

1type Cart = { items: number; coupon: string };2 3function on(event: `${keyof Cart}Changed`, handler: (value: unknown) => void) {4  console.log(`Listening for ${event}`);5}6 7on("couponChanged", (value) => {8  console.log(value.toUpperCase());9});

1type Cart = { items: number; coupon: string };2 3function on<K extends keyof Cart>(event: `${K}Changed`, handler: (value: Cart[K]) => void) {4  console.log(`Listening for ${event}`);5}6 7on("couponChanged", (value) => {8//                   ^?9  console.log(value.toUpperCase());10});

Check your understanding

For each question, write out the strings the pattern makes before you choose. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A template literal type is written like a template literal, with types in the placeholders, like `btn-${Size}`.
• A union in a placeholder makes one string per member. Two unions make every combination, so the counts multiply.
• string and number in a placeholder make open patterns, like `${number}px`. boolean allows only the text "true" or "false".
• Uppercase, Lowercase, Capitalize, and Uncapitalize change the case of string types, not values.
• `${keyof T}Changed` builds event names from an object's keys, and a generic K lets the handler's value follow the name.
• Text that arrives while the page runs is only a string. Check it before you use it as a pattern type.

Coming next: Partial, Pick, Omit & friends. It covers TypeScript's built-in helpers that make new object types from old ones, like every property optional for a form update.