Runnable TypeScript Docs: Switch Statement

Q: How do you write a switch statement in TypeScript?

Exactly as in JavaScript: switch (value) { case "a": ...; break; default: ... }. Cases are compared with ===. TypeScript adds checks: a case value that can never match the switched type is an error (TS2678), and inside each case the switched variable is narrowed to that case.

Q: How do I make a switch exhaustive in TypeScript?

Add a default that assigns the value to a variable of type never: default: { const unreachable: never = value; throw new Error(...) }. When every member of the union is handled, the value is never there and it compiles. When one is missing, the compiler reports the missing member (TS2322).

Q: How do I handle multiple cases with the same code in a TypeScript switch?

Stack the labels with no code between them: case "sat": case "sun": return "weekend";. Empty cases fall through to the next one. The noFallthroughCasesInSwitch option only reports cases that have code and no break or return, so stacked labels stay allowed.

Q: Does switch (true) narrow types in TypeScript?

Yes, since TypeScript 5.3. In switch (true) { case typeof x === "string": ... }, x is narrowed to string inside that case, just as it would be in an if. It is a readable alternative to a chain of if/else if with range or type checks.

A TypeScript switch statement is JavaScript's switch with type checking. It compares a value against each case with ===, runs the matching branch, and stops at break or return. TypeScript narrows the switched value inside each case and can check that every possible value is handled.

type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";

function describe(day: Weekday): string {
    switch (day) {
        case "sat":
        case "sun":
            return "weekend";
        case "fri":
            return "almost weekend";
        default:
            return "workday";
    }
}

console.log(describe("sun")); // weekend
console.log(describe("fri")); // almost weekend
console.log(describe("tue")); // workday

Stacked labels (case "sat": case "sun":) share one branch. return ends the function, so no break is needed after it.

Syntax

switch (expression) {
    case value1:
        // runs when expression === value1
        break;
    case value2:
    case value3:
        // runs for value2 or value3
        break;
    default:
        // runs when nothing else matched
}

Matching uses strict equality, ===: case 1 does not match the string "1".
Without break, return or throw, execution continues into the next case (fallthrough).
default is optional and can sit anywhere, though last is conventional.
A case value TypeScript can prove never matches is error TS2678. For a parameter typed "a" | "b", case "c": reports Type '"c"' is not comparable to type '"a" | "b"'., which catches typos in case labels.

Narrowing Inside Each Case

In each case, TypeScript knows which value matched and narrows the type. This is most useful with a discriminated union: switch on the shared tag property, and each case sees the matching variant with its own properties.

type Shape =
    | { kind: "circle"; radius: number }
    | { kind: "rect"; width: number; height: number }
    | { kind: "square"; side: number };

function area(shape: Shape): number {
    switch (shape.kind) {
        case "circle":
            return Math.PI * shape.radius ** 2; // shape: circle variant
        case "rect":
            return shape.width * shape.height;  // shape: rect variant
        case "square":
            return shape.side ** 2;             // shape: square variant
    }
}

console.log(area({ kind: "circle", radius: 1 }).toFixed(2)); // 3.14
console.log(area({ kind: "rect", width: 2, height: 3 }));    // 6
console.log(area({ kind: "square", side: 4 }));              // 16

shape.radius compiles only in the "circle" case. Outside it, shape might be a rectangle, which has no radius. There is no default, and the function still type-checks as returning number, because TypeScript sees that the three cases cover every kind. More patterns built on this are on the discriminated unions page.

Exhaustive Switch with never

The function above stops compiling if a fourth shape is added without a case (TS2366, a missing return). That only works when the function returns a value. For a guarantee that also works in void code and gives a clearer message, add a default that assigns the value to never:

// This does not compile: the "triangle" case is missing.
type Shape =
    | { kind: "circle"; radius: number }
    | { kind: "square"; side: number }
    | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
    switch (shape.kind) {
        case "circle":
            return Math.PI * shape.radius ** 2;
        case "square":
            return shape.side ** 2;
        default: {
            const unreachable: never = shape;
            throw new Error(`Unknown shape: ${JSON.stringify(unreachable)}`);
        }
    }
}

console.log(area({ kind: "square", side: 3 }));

index.ts(14,19): error TS2322: Type '{ kind: "triangle"; base: number; height: number; }' is not assignable to type 'never'.

After the handled cases, the only type left for shape is the triangle variant, and it cannot be assigned to never. The error names exactly what is missing. Add case "triangle": return (shape.base * shape.height) / 2; and the default sees never, so the block compiles and prints 9. The throw still guards against bad data at runtime, such as a kind from JSON that the types did not anticipate.

Many codebases wrap the check in a helper:

function assertNever(value: never): never {
    throw new Error(`Unhandled value: ${JSON.stringify(value)}`);
}

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

function label(status: Status): string {
    switch (status) {
        case "idle": return "Waiting";
        case "loading": return "Loading...";
        case "done": return "Finished";
        default: return assertNever(status);
    }
}

console.log(label("loading")); // Loading...

The same technique works for enums: switch on the enum value and pass it to assertNever in the default.

switch (true) for Ranges and Conditions

switch compares values, so ranges need a trick: switch on true and write a condition in each case. Since TypeScript 5.3, those conditions narrow types just like if statements do.

function grade(score: number): string {
    switch (true) {
        case score >= 90: return "A";
        case score >= 80: return "B";
        case score >= 70: return "C";
        default: return "F";
    }
}

function format(value: string | number | boolean): string {
    switch (true) {
        case typeof value === "string":
            return value.toUpperCase();   // value: string
        case typeof value === "number":
            return value.toFixed(2);      // value: number
        default:
            return value ? "yes" : "no";  // value: boolean
    }
}

console.log(grade(85), grade(42));                     // B F
console.log(format("hi"), format(3.14159), format(true)); // HI 3.14 yes

Cases are tested in order, so put the most specific first. Whether this reads better than if / else if is a matter of taste; the behavior is the same.

Fallthrough and break

A case with code but no break, return or throw falls through into the next case. That is almost always a bug. The compiler option noFallthroughCasesInSwitch (not part of strict) turns it into error TS7029, Fallthrough case in switch., while still allowing stacked empty labels.

function permissions(role: "admin" | "editor" | "viewer"): string[] {
    const result: string[] = [];
    switch (role) {
        case "admin":
            result.push("delete");
        // intentional fallthrough: admins can also edit
        case "editor":
            result.push("edit");
        // intentional fallthrough: editors can also view
        case "viewer":
            result.push("view");
    }
    return result;
}

console.log(permissions("admin"));  // [ 'delete', 'edit', 'view' ]
console.log(permissions("viewer")); // [ 'view' ]

Deliberate fallthrough like this works, but with noFallthroughCasesInSwitch on it must be rewritten, for example with separate if checks. That is usually clearer anyway.

Variables Inside Cases

The whole switch body is one block, so a const declared in one case is visible (and a redeclaration is an error) in the others. Wrap a case in braces to give it its own scope:

function price(item: "tea" | "cake", qty: number): number {
    switch (item) {
        case "tea": {
            const unit = 2.5;
            return unit * qty;
        }
        case "cake": {
            const unit = 4; // fine: a different block
            return unit * qty;
        }
    }
}

console.log(price("tea", 2), price("cake", 3)); // 5 12

Without the braces, the second const unit is compile error TS2451, Cannot redeclare block-scoped variable 'unit'.

switch vs Object Lookup

When each case only maps a value to another value, an object typed with Record is shorter, and TypeScript checks that every key is present:

type Level = "debug" | "info" | "warn" | "error";

const icons: Record<Level, string> = {
    debug: "[D]",
    info: "[I]",
    warn: "[W]",
    error: "[E]",
};

console.log(icons.warn, icons["error"]); // [W] [E]

Leaving out a key is a compile error, which gives the same exhaustiveness as a never check. Keep switch for cases that run different logic, narrow union variants, or return early.

Frequently Asked Questions

How do you write a switch statement in TypeScript?

Exactly as in JavaScript: switch (value) { case "a": ...; break; default: ... }. Cases are compared with ===. TypeScript adds checks: a case value that can never match the switched type is an error (TS2678), and inside each case the switched variable is narrowed to that case.

How do I make a switch exhaustive in TypeScript?

Add a default that assigns the value to a variable of type never: default: { const unreachable: never = value; throw new Error(...) }. When every member of the union is handled, the value is never there and it compiles. When one is missing, the compiler reports the missing member (TS2322).

How do I handle multiple cases with the same code in a TypeScript switch?

Stack the labels with no code between them: case "sat": case "sun": return "weekend";. Empty cases fall through to the next one. The noFallthroughCasesInSwitch option only reports cases that have code and no break or return, so stacked labels stay allowed.

Does switch (true) narrow types in TypeScript?

Yes, since TypeScript 5.3. In switch (true) { case typeof x === "string": ... }, x is narrowed to string inside that case, just as it would be in an if. It is a readable alternative to a chain of if/else if with range or type checks.

Related concepts