Template literal types and intrinsic string types

Template literal types plus Uppercase, Lowercase, Capitalize, and Uncapitalize, including union distribution and why those intrinsics are not locale-aware casing.

主题页正文目前为英文。

Template literal types build string literal types from other string types, using the same backtick syntax as JavaScript template strings. They arrived in TypeScript 4.1. Number, bigint, boolean, null, and undefined interpolations are also allowed. Unions in any interpolation position expand into a finite cross product of literals.

Uppercase, Lowercase, Capitalize, and Uncapitalize are intrinsic string-manipulation types from the same release. Their declarations have the form type Uppercase<S extends string> = intrinsic. They rewrite string literal types at compile time. They are not String.toLocaleUpperCase, they are not Intl, and they do not promise locale-specific casing such as Turkish dotted and dotless I.

Examples were checked with TypeScript 5.9.3 using tsc --strict. See the TypeScript handbook for the complete utility-type catalog.

TypeScript reference overview →

API index

APISummary
Template literal typesBuild new string literal types from existing ones. Unions in interpolations expand to every combination.
Uppercase, Lowercase, Capitalize, UncapitalizeRewrite string literal types with intrinsic case mapping. The mapping is not locale-aware and is not a runtime string method.

Template literal types

EventName and Handler below are template literal types. When the type argument is a string literal, the result is a new literal. When it is a union, each member is substituted. Capitalize can be applied inside a template, so a handler type turns "click" | "focus" into "onClick" | "onFocus". The examples were checked with TypeScript 5.9.3 under tsc --strict.

Template literal types

type EventName<T extends string> = `${T}Changed`;
type Handler<T extends string> = `on${Capitalize<T>}`;

Build new string literal types from existing ones. Unions in interpolations expand to every combination.

Type parameterDescription
TUsually a string literal or a union of literals. A constraint such as extends string keeps the template from accepting unrelated types.

Produces: A string literal type, or a union of them when the input interpolations are unions.

Type errors

  • type error — A string that does not match the resulting literal union is not assignable, such as "onclick" where the type requires "onClick".
  • Template literal types were added in TypeScript 4.1. They exist only at compile time.
typescript
type EventName<T extends string> = `${T}Changed`;
type Handler<T extends string> = `on${Capitalize<T>}`;

const ev: EventName<"foo"> = "fooChanged";
const click: Handler<"click" | "focus"> = "onClick";
const focusEvent: Handler<"click" | "focus"> = "onFocus";
// @ts-expect-error "onclick" is not Capitalize<"click">
const bad: Handler<"click"> = "onclick";
// @ts-expect-error the union does not include "change"
const missing: EventName<"foo" | "bar"> = "changeChanged";

type Cross = `${"a" | "b"}-${"1" | "2"}`;
const c: Cross = "a-1";
console.log(ev, click, c);

Expected output

fooChanged onClick a-1

Related: Capitalize, Mapped key remapping

Official documentation →

Uppercase, Lowercase, Capitalize, and Uncapitalize

These four aliases are declared as intrinsic in TypeScript 5.9.3 lib.es5.d.ts, with a type argument that extends string. Uppercase of "Hello" is "HELLO". Capitalize changes only the first character: Capitalize of "click" is "Click". They distribute over unions: Uppercase of "a" | "b" is "A" | "B".

The mapping is not a locale-sensitive API. Uppercase of "i" is "I", not a Turkish dotted I. On TypeScript 5.9.3, Uppercase of the eszett character produces "SS", and Capitalize of "ßeta" is "SSeta" because that first character maps to two characters. Do not treat these types as Intl or toLocaleUpperCase. Uppercase applied to string is not the same as string: a general string is not assignable to that result.

Uppercase, Lowercase, Capitalize, Uncapitalize

type Uppercase<S extends string> = intrinsic;
type Lowercase<S extends string> = intrinsic;
type Capitalize<S extends string> = intrinsic;
type Uncapitalize<S extends string> = intrinsic;

Rewrite string literal types with intrinsic case mapping. The mapping is not locale-aware and is not a runtime string method.

Type parameterDescription
SA type that extends string, usually a string literal or a union of literals. Uppercase of a number type is a type error.

Produces: A string literal type, a union of literals, or an unresolved intrinsic type such as Uppercase applied to string.

Type errors

  • type error — The type argument must extend string. A literal that is not the mapped result, such as "Hello" for Uppercase of "Hello", is not assignable.
  • The signatures are from TypeScript 5.9.3 lib.es5.d.ts. These aliases were added in TypeScript 4.1.
  • The ß and i results were measured with this project TypeScript 5.9.3. They illustrate the intrinsic mapping; they are not a claim about every Unicode character or every locale.
typescript
type Up = Uppercase<"Hello">;
type Down = Lowercase<"Hello">;
type Cap = Capitalize<"click">;
type Uncap = Uncapitalize<"Click">;

const up: Up = "HELLO";
const down: Down = "hello";
const cap: Cap = "Click";
const uncap: Uncap = "click";
// @ts-expect-error "Hello" is not Uppercase<"Hello">
const notUp: Up = "Hello";

type Sharp = Uppercase<"ß">;
const sharp: Sharp = "SS";
// @ts-expect-error the intrinsic mapping of "ß" is "SS"
const eszett: Sharp = "ß";

type CapitalSharp = Capitalize<"ßeta">;
const title: CapitalSharp = "SSeta";
// @ts-expect-error Capitalize maps the first character, and "ß" becomes "SS"
const notTitle: CapitalSharp = "ßeta";

const upperI: Uppercase<"i"> = "I";
// @ts-expect-error this intrinsic mapping is not a Turkish locale I
const turkish: Uppercase<"i"> = "İ";

// @ts-expect-error Uppercase constrains its type argument to string
type Bad = Uppercase<number>;

console.log(up, sharp, title, upperI);

Expected output

HELLO SS SSeta I

Related: Template literal types

Official documentation →