TypeScript Template Literal Types: Syntax and Examples

A template literal type builds string literal types with the same backtick syntax as a JavaScript template string. `on${Capitalize<"click" | "focus">}` is the type "onClick" | "onFocus", computed by the compiler:

type DomEvent = "click" | "focus" | "blur";

type HandlerName = `on${Capitalize<DomEvent>}`;
// "onClick" | "onFocus" | "onBlur"

const handlers: Record<HandlerName, () => string> = {
  onClick: () => "clicked",
  onFocus: () => "focused",
  onBlur: () => "blurred",
};

console.log(handlers.onFocus()); // focused
// @ts-expect-error: "onHover" is not one of the handler names
handlers.onHover;

Template literal types exist only at compile time. They check string literals and typed values while you write code; they add nothing to the JavaScript output. The handler table above uses Record to require one function per name.

Syntax

Inside the backticks you write literal text and ${...} placeholders. A placeholder holds a type, not a value: a string, number, bigint or boolean literal type, a union of them, or one of the wide types string, number, bigint, boolean, null and undefined.

type Greeting = `hello ${string}`;   // any string that starts with "hello "
type Version = `v${number}`;         // "v1", "v2.5", ...
type Toggle = `is-${boolean}`;       // "is-true" | "is-false"

const g: Greeting = "hello Ada";
const v: Version = "v3";
const t: Toggle = "is-false";

// @ts-expect-error: Type '"hi Ada"' is not assignable to type '`hello ${string}`'
const wrong: Greeting = "hi Ada";

console.log(g, v, t); // hello Ada v3 is-false

A placeholder with a wide type like string or number makes a pattern: the type stays as `hello ${string}` and any matching string is accepted. A placeholder with a finite union, like boolean, is expanded into its members.

Unions Multiply

With several unions, the result is every combination:

type Size = "sm" | "md" | "lg";
type Tone = "primary" | "danger";

type ButtonClass = `btn-${Size}-${Tone}`;
// "btn-sm-primary" | "btn-sm-danger" | "btn-md-primary" | ... (6 members)

function button(cls: ButtonClass): string {
  return `<button class="${cls}">`;
}

console.log(button("btn-lg-danger")); // <button class="btn-lg-danger">
// button("btn-xl-danger") would be error TS2345

Three sizes times two tones gives six members. The count grows fast: five placeholders that each hold a union of ten letters would be 100,000 members, and TypeScript refuses with error TS2590: Expression produces a union type that is too complex to represent. Use a wide placeholder like ${string} when you do not need every exact value.

Uppercase, Lowercase, Capitalize, Uncapitalize

Four built-in types change the case of string literal types. They are intrinsic: implemented inside the compiler, not written in TypeScript.

They change types only. To build the matching runtime string, you still call toUpperCase() or slice and capitalize yourself, and tell TypeScript the result has the precise type:

function capitalize<S extends string>(s: S): Capitalize<S> {
  return (s.charAt(0).toUpperCase() + s.slice(1)) as Capitalize<S>;
}

const title = capitalize("report"); // type "Report"
const loud: Uppercase<"ok"> = "OK";

console.log(title, loud); // Report OK

The as is needed because toUpperCase() is typed to return plain string. The function's signature is what callers see, so capitalize("report") has the literal type "Report".

String Patterns: ${number}px and Friends

A pattern type accepts every string of a given shape. It is handy for CSS values, ids and keys with a known prefix:

type Pixels = `${number}px`;
type UserId = `user_${string}`;
type Semver = `${number}.${number}.${number}`;

function setWidth(w: Pixels) {
  return `width: ${w}`;
}

const id: UserId = "user_42";
const version: Semver = "7.0.2";

console.log(setWidth("120px"), id, version); // width: 120px user_42 7.0.2
// setWidth("120") and setWidth("wide px") would both be error TS2345

${number} accepts any string that JavaScript reads as a number, which is looser than it looks: "-3px", "1e3px" and "0x10px" all type-check. Treat these patterns as a guard against typos in literals, not as full validation.

Template Literals with Mapped Types

Template literal types are most useful as the as clause of a mapped type, where they generate property names from other property names:

type Watchers<T> = {
  [K in keyof T as `on${Capitalize<string & K>}Change`]: (value: T[K]) => void;
};

type Form = { email: string; age: number };

// { onEmailChange: (value: string) => void; onAgeChange: (value: number) => void }
const watch: Watchers<Form> = {
  onEmailChange: (v) => console.log("email is now", v),
  onAgeChange: (v) => console.log("age is now", v.toFixed(0)), // v is number
};

watch.onEmailChange("ada@example.com"); // email is now ada@example.com
watch.onAgeChange(37);                  // age is now 37

string & K keeps only string keys, since Capitalize does not accept numbers or symbols. Each callback gets its parameter type from the property it watches.

Parsing Strings with infer

In a conditional type, a template literal can match a string and capture parts of it with infer. This extracts the parameter names from a route pattern:

type RouteParams<S extends string> =
  S extends `${string}:${infer Param}/${infer Rest}`
    ? Param | RouteParams<`/${Rest}`>
    : S extends `${string}:${infer Param}`
      ? Param
      : never;

type P = RouteParams<"/users/:userId/posts/:postId">; // "userId" | "postId"

function link<S extends string>(pattern: S, params: Record<RouteParams<S>, string>): string {
  return pattern.replace(/:(\w+)/g, (_, key: string) => params[key as RouteParams<S>]);
}

console.log(link("/users/:userId/posts/:postId", { userId: "7", postId: "42" }));
// /users/7/posts/42

Leave out postId in the call and the compiler reports it as missing.

Template Expressions Widen to string

A template string expression in ordinary code is typed string, even when every part is a literal type. Add as const to keep the template literal type:

type Level = "info" | "warn";

function tag(level: Level) {
  const loose = `log:${level}`;          // string
  const exact = `log:${level}` as const; // "log:info" | "log:warn"
  return { loose, exact };
}

const { exact } = tag("warn");
const again: `log:${Level}` = exact; // OK: the exact type fits
console.log(exact, again);           // log:warn log:warn

Without as const, assigning loose to `log:${Level}` fails, because string could be anything.