TypeScript Reference ยท Primitive and Special Types
TypeScript template literal types
Reference for TypeScript template literal types: build string types from unions, infer parts with infer, and combine with mapped types and key remapping.
A template literal type uses the same backtick syntax as a JavaScript template string, but in a type position. It produces a string literal type from other types: `user-${number}` accepts "user-1" and "user-42" but not "admin-1".
When a placeholder is a union, TypeScript produces every combination, so `${"get" | "set"}${"X" | "Y"}` is a four-member union. In a conditional type, a template pattern with infer can also take strings apart. This makes template literal types the tool for typing event names, route paths, CSS-like units and generated property names.
type Id = `user-${number}`; const ok: Id = "user-7";
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
type T1 = `prefix-${string}`; type T2 = `${number}px`; type T3 = `${A}-${B}`; // A and B unions: all combinations type T4<S> = S extends `${infer H}${infer R}` ? [H, R] : never;
| Part | Description |
|---|---|
`text` |
A string literal type written with backticks. |
${T} |
Placeholder. T must be string, number, bigint, boolean, null, undefined or a literal/union of those. |
infer X |
Captures the matched substring inside a conditional type. |
Edge cases:
- A union in a placeholder multiplies. Unions with many members make an enormous type, and TypeScript stops at 100,000 members with an error ("Expression produces a union type that is too complex to represent").
`${string}`is juststring;`${number}`accepts anything that round-trips throughNumberstring conversion, like"1e3"or"-0.5".- When
inferis followed immediately by anotherinferwith no literal text between, the first captures a single character and the second the rest. - Matching is exact and case-sensitive; use the intrinsic types to change case.
Usage notes
- Typed event names.
`on${Capitalize<EventName>}`derives handler names from a union. - Key remapping. Combine with mapped types using
asto rename keys (getters, setters, prefixes). - Parsing. Recursive conditional types can split on a separator, but long strings hit the recursion limit, so keep inputs short.
- Runtime unaffected. Values are ordinary strings; the checking applies only to literals the compiler can see. A value typed as
stringcannot be assigned to a pattern type without a check or assertion. - Pattern types and narrowing.
startsWithdoes not narrow to`prefix${string}`; write a type guard function. - Version notes. Template literal types arrived in TypeScript 4.1; the intrinsic case types in 4.1 too, and
inferwithextendsconstraints in 4.7.