TypeScript Academy · Lesson

String and Numeric Literal Types

Restrict values to exact strings and numbers with literal types.

String and Numeric Literal Types is a free TypeScript Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the TypeScript Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What Is a Literal Type?

Most types describe a set of values. string means any string, number means any number. A literal type narrows this down to one exact value.

The type 'north' only allows the string 'north' — nothing else. Literal types let you model precise, finite sets of allowed values right in the type system.

let dir: 'north' = 'north';
console.log(dir);
// dir = 'south'; // Error: not assignable to type 'north'

String Literal Unions

A single literal isn't very useful alone. Combine several with | to form a union of literals. This is the idiomatic way to model a fixed set of options.

Direction below can only ever be one of four exact strings.

type Direction = 'north' | 'south' | 'east' | 'west';

let heading: Direction = 'east';
console.log('Heading:', heading);

heading = 'west';
console.log('Now:', heading);

Rejecting Invalid Values

The power of literal unions is that the compiler rejects anything outside the allowed set. Typos and invalid options become compile-time errors instead of runtime bugs.

type Direction = 'north' | 'south' | 'east' | 'west';

let heading: Direction = 'north';
console.log(heading);
// heading = 'up'; // Error: '"up"' is not assignable to 'Direction'

Literals as Function Parameters

Use literal unions for function parameters that accept only specific values. The caller gets autocomplete and is blocked from passing anything invalid.

type Direction = 'north' | 'south' | 'east' | 'west';

function move(dir: Direction): string {
  return 'Moving ' + dir;
}

console.log(move('south'));
// console.log(move('left')); // Error

Numeric Literal Types

Literal types aren't just for strings. You can use exact numbers too. A classic example is a six-sided die, whose face value must be one of 1 through 6.

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

function roll(): Dice {
  return (Math.floor(Math.random() * 6) + 1) as Dice;
}

console.log('Rolled:', roll());

Numeric Literals in Parameters

Numeric literal unions constrain inputs to an exact set of numbers — perfect for things like quality levels, HTTP-like codes, or grid sizes.

type Quality = 1 | 2 | 3;

function setQuality(level: Quality): void {
  console.log('Quality set to', level);
}

setQuality(2);
// setQuality(5); // Error: 5 is not 1 | 2 | 3

Mixing String and Numeric Literals

A union can blend literal kinds. This is handy for APIs that accept either a named preset or a raw value.

type Size = 'small' | 'large' | 0 | 100;

function resize(s: Size): void {
  console.log('Resizing to', s);
}

resize('small');
resize(100);

Boolean Literal Types

Even booleans have literal types: true and false are types as well as values. The full boolean type is really just true | false.

type AlwaysOn = true;

let enabled: AlwaysOn = true;
console.log('Enabled:', enabled);
// enabled = false; // Error: false not assignable to true

Literals Improve Documentation

A literal union doubles as documentation. Anyone reading type Status = 'idle' | 'loading' | 'done' instantly knows every possible state — no guessing, no magic strings scattered across the code.

type Status = 'idle' | 'loading' | 'done';

function render(s: Status): string {
  return 'State is: ' + s;
}

console.log(render('loading'));

Combining Literals With Other Types

You can mix literal types with broader types in a union. A common pattern is 'auto' | number, meaning either the special keyword 'auto' or any number.

type Width = 'auto' | number;

function setWidth(w: Width): void {
  console.log('Width:', w);
}

setWidth('auto');
setWidth(320);

Literals as Named Constants

Literal types pair beautifully with named constants. Define the type once, reuse it everywhere, and refactor safely. The compiler keeps every usage consistent.

type Theme = 'light' | 'dark';

const DEFAULT_THEME: Theme = 'dark';

function applyTheme(t: Theme): void {
  console.log('Applying', t, 'theme');
}

applyTheme(DEFAULT_THEME);

Quick Check

Test your understanding of literal types.

Recap: Literal Types

You learned that:

Literal types represent one exact value, e.g. 'north' or 6.
Combining literals with | creates a finite union of allowed values.
They work for strings, numbers, and booleans, and can mix with broader types like 'auto' | number.
Used as function parameters, they give autocomplete and reject invalid inputs at compile time.

Next, we explore how TypeScript decides between literal and widened types.

type Direction = 'north' | 'south' | 'east' | 'west';
type Dice = 1 | 2 | 3 | 4 | 5 | 6;

function describe(d: Direction, n: Dice): string {
  return 'Go ' + d + ' ' + n + ' steps';
}

console.log(describe('north', 3));

Frequently asked questions

Is the “String and Numeric Literal Types” lesson free?

Yes — the full text of “String and Numeric Literal Types” is free to read here on the web, and the TypeScript Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the TypeScript Academy course, upgrade to CoddyKit PRO.

What will I learn in “String and Numeric Literal Types”?

Restrict values to exact strings and numbers with literal types. You practise TypeScript Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start TypeScript Academy?

No prior experience is required. TypeScript Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “String and Numeric Literal Types” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this TypeScript Academy lesson?

Yes. Every TypeScript Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to TypeScript Academy