TypeScript Template Literal Types: Syntax und Beispiele

Ein Template Literal Type baut String-Literaltypen mit derselben Backtick-Syntax wie ein Template String in JavaScript. `on${Capitalize<"click" | "focus">}` ist der Typ "onClick" | "onFocus", berechnet vom 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 existieren nur beim Kompilieren. Sie prüfen String-Literale und typisierte Werte, während du Code schreibst; zur JavaScript-Ausgabe tragen sie nichts bei. Die Handler-Tabelle oben nutzt Record, um eine Funktion pro Name zu verlangen.

Syntax

Zwischen die Backticks schreibst du literalen Text und Platzhalter ${...}. Ein Platzhalter enthält einen Typ, keinen Wert: einen Literaltyp für string, number, bigint oder boolean, eine Union davon oder einen der breiten Typen string, number, bigint, boolean, null und 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

Ein Platzhalter mit einem breiten Typ wie string oder number ergibt ein Muster: Der Typ bleibt `hello ${string}`, und jeder passende String wird akzeptiert. Ein Platzhalter mit einer endlichen Union wie boolean wird in ihre Mitglieder aufgelöst.

Unions multiplizieren sich

Bei mehreren Unions ist das Ergebnis jede Kombination:

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

Drei Größen mal zwei Farbtöne ergibt sechs Mitglieder. Die Anzahl wächst schnell: Fünf Platzhalter mit je einer Union aus zehn Buchstaben ergäben 100,000 Mitglieder, und TypeScript verweigert das mit error TS2590: Expression produces a union type that is too complex to represent. Nimm einen breiten Platzhalter wie ${string}, wenn du nicht jeden genauen Wert brauchst.

Uppercase, Lowercase, Capitalize, Uncapitalize

Vier eingebaute Typen ändern die Groß- und Kleinschreibung von String-Literaltypen. Sie sind intrinsisch: im Compiler implementiert, nicht in TypeScript geschrieben.

Sie ändern nur Typen. Um den passenden String zur Laufzeit zu bauen, rufst du weiterhin toUpperCase() auf oder schneidest den String zurecht und schreibst ihn selbst groß, und sagst TypeScript, dass das Ergebnis den genauen Typ hat:

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

Das as ist nötig, weil toUpperCase() so typisiert ist, dass es einen einfachen string zurückgibt. Aufrufer sehen die Signatur der Funktion, also hat capitalize("report") den Literaltyp "Report".

String-Muster: ${number}px und Co.

Ein Mustertyp akzeptiert jeden String einer bestimmten Form. Das ist praktisch für CSS-Werte, IDs und Schlüssel mit bekanntem Präfix:

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} akzeptiert jeden String, den JavaScript als Zahl liest, und das ist lockerer, als es aussieht: "-3px", "1e3px" und "0x10px" bestehen alle die Typprüfung. Betrachte diese Muster als Schutz vor Tippfehlern in Literalen, nicht als vollständige Validierung.

Template Literals mit Mapped Types

Am nützlichsten sind Template Literal Types als as-Klausel eines Mapped Types, wo sie Eigenschaftsnamen aus anderen Eigenschaftsnamen erzeugen:

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 behält nur String-Schlüssel, weil Capitalize keine Zahlen oder Symbole akzeptiert. Jeder Callback bekommt seinen Parametertyp von der Eigenschaft, die er beobachtet.

Strings mit infer zerlegen

In einem Conditional Type kann ein Template Literal einen String abgleichen und Teile davon mit infer festhalten. So werden die Parameternamen aus einem Routenmuster herausgezogen:

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

Lässt du postId im Aufruf weg, meldet der Compiler es als fehlend.

Template-Ausdrücke werden zu string erweitert

Ein Template-String-Ausdruck in normalem Code ist als string typisiert, auch wenn jeder Teil ein Literaltyp ist. Ergänze as const, um den Template Literal Type zu behalten:

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

Ohne as const scheitert die Zuweisung von loose an `log:${Level}`, weil string alles sein könnte.