TypeScript Reference ยท Literal and Object Types
TypeScript string literal types
Reference for string literal types in TypeScript: exact string values as types, unions of literals, widening with let and const, and as const.
A string literal type is a type that contains exactly one string value. You write it the same way you write the string: "north" as a type allows only the value "north". On its own that is rarely useful, but a union of several string literals describes a fixed set of allowed strings, which is how TypeScript models option names, event names, HTTP verbs and state labels.
The compiler checks the exact characters, including case and spaces, and editors autocomplete the allowed values. A typo becomes a compile-time error instead of a bug found in production.
type Direction = "north" | "south" | "east" | "west";
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.
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 Name = "literal"; type Union = "a" | "b" | "c"; const c = "text"; // type "text" let v: "yes" | "no" = "yes";
| Form | Description |
|---|---|
"text" |
The type containing only that string. Quotes may be single, double or backtick (without substitutions). |
"a" | "b" |
A union: the value must be one of the listed strings. |
as const |
Keeps object and array contents as literal types and makes them readonly. |
typeof x[number] |
Turns the elements of a literal tuple into a union type. |
Edge cases: string is a supertype of every string literal, so "a" is assignable to string, but string is not assignable to "a". The empty string "" is also a valid literal type.
Usage notes
- Widening:
const x = "a"has type"a", butlet x = "a"and object properties such as{ kind: "a" }are inferred asstring. Use an annotation,as constorsatisfiesto keep the literal. The "Widening with let" example fails on purpose to show the real compiler error. - A function parameter typed
stringaccepts any literal, but a parameter typed as a union rejects plainstringvariables. Narrow them with a type guard first. - Template literal types build new string types from literals, such as
`on${Capitalize<Event>}`. - In a discriminated union, a string literal property is the usual tag, and
switchover it is checked for exhaustiveness. - Enums and literal unions solve the same problem. A union has no runtime object and no import cost, while an
enumcreates one; many teams prefer unions for string sets. - Comparing a value to a literal outside its type is an error:
if (level === "warn")fails whenLevelhas no"warn". - Property names in
keyofresults are string literal types, which is whykeyofcomposes well with other literal-based types. - A very large union of literals slows the compiler; if you have hundreds of values, consider plain
stringplus a runtime check.