Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
type Dice = 1 | 2 | 3 | 4 | 5 | 6;

Try it

TypeScript A union of numbers

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.

TypeScript Rejecting values outside the set

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

TypeScript
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 = 3 widens to number, which is not assignable to Version.
  • A const declaration keeps the literal type; let and mutable object properties widen to number. as const keeps them narrow.
  • Arithmetic on literals produces plain number. 1 + 2 is typed number, not 3, so you need an assertion or a lookup table to return a literal type.
  • The compiler can check switch over a literal union for exhaustiveness. Without a default, a missing case makes the function's return type include undefined (error 2366 under strict).
  • Comparisons that can never be true are rejected: with Version = 1 | 2, version === 3 is an error because the types do not overlap.
  • Literal numbers as object keys become property names: { 1: "a" } has a key 1, which is also reachable as "1".
  • Tuple lengths are number literal types: [string, string]["length"] is 2. This is the basis of many type-level counters.
  • Prefer a lookup Record<Status, string> over a switch when 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.