TypeScript Reference ยท Literal and Object Types
TypeScript number literal types
Reference for number literal types in TypeScript: exact numeric values as types, unions like 1 | 2 | 3, negative and hex literals, widening and as const.
A number literal type contains exactly one numeric value. The type 3 allows only the number 3; the type 1 | 2 | 3 allows any of the three. This is handy for dice, severity levels, HTTP status codes, protocol versions and any small fixed set of numbers where an arbitrary number would be too permissive.
Numeric literal types can be written in decimal, hex (0xff), octal (0o17), binary (0b101) and with numeric separators (1_000). They are normalized: the types 0xff and 255 are the same type. Negative numbers are allowed (-1), written with a leading minus sign.
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
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 One = 1; type Few = 1 | 2 | 3; type Neg = -1; const n = 42; // type 42 let m: 0 | 1 = 0;
| Form | Description |
|---|---|
42 |
The type containing only the number 42. |
-1 |
Negative literal; the minus is part of the type syntax. |
0xff, 1_000 |
Hex and separated forms; they are equal to 255 and 1000. |
1 | 2 |
Union of literals. |
Edge cases: NaN, Infinity and -0 have no literal types. Large or fractional literals work (0.5), but comparing floating-point results to them is risky. number is the supertype of every number literal; bigint literals (10n) are a separate family.
Usage notes
- The "Rejecting values outside the set" example fails on purpose:
let next = 3widens tonumber, which is not assignable toVersion. - A
constdeclaration keeps the literal type;letand mutable object properties widen tonumber.as constkeeps them narrow. - Arithmetic on literals produces plain
number.1 + 2is typednumber, not3, so you need an assertion or a lookup table to return a literal type. - The compiler can check
switchover a literal union for exhaustiveness. Without adefault, a missing case makes the function's return type includeundefined(error 2366 understrict). - Comparisons that can never be true are rejected: with
Version = 1 | 2,version === 3is an error because the types do not overlap. - Literal numbers as object keys become property names:
{ 1: "a" }has a key1, which is also reachable as"1". - Tuple lengths are number literal types:
[string, string]["length"]is2. This is the basis of many type-level counters. - Prefer a lookup
Record<Status, string>over aswitchwhen every code maps to a value; the compiler then demands an entry for each key. - A union of dozens of numbers is fine, but ranges such as "0 to 100" cannot be expressed. Validate those at runtime or with a branded type.