TypeScript Tuple: Syntax, Named, Optional and Rest Elements

A TypeScript tuple is an array with a fixed number of elements, where each position has its own type. [string, number] means exactly two elements: a string first, then a number. You write the types in square brackets in the order the values appear.

// A tuple type: position 0 is a string, position 1 is a number
let user: [string, number] = ["Ada", 36];

const userName = user[0]; // string
const age = user[1];      // number
console.log(userName.toUpperCase(), age + 1); // ADA 37

// Destructuring gives each element its own type
const [n, a] = user;
console.log(`${n} is ${a}`); // Ada is 36

user = ["Grace", 85];     // fine: same shape
console.log(user, user.length); // [ 'Grace', 85 ] 2

At runtime a tuple is a plain JavaScript array. Everything a tuple adds (the fixed length and the type at each position) is checked by the compiler and erased.

Tuple Syntax

Each form is explained below. The type of length is worth noticing: for a fixed tuple it is a literal type, so the compiler knows pair.length is exactly 2.

What the Compiler Checks

A tuple type fixes the number of elements, their order, and the type at each position. Getting any of them wrong is a compile error:

// This does not compile: wrong length, wrong order, index out of range.
const tooShort: [string, number] = ["Ada"];
const swapped: [string, number] = [36, "Ada"];
const ok: [string, number] = ["Ada", 36];
console.log(ok[2]);

index.ts(2,7): error TS2322: Type '[string]' is not assignable to type '[string, number]'.
  Source has 1 element(s) but target requires 2.
index.ts(3,36): error TS2322: Type 'number' is not assignable to type 'string'.
index.ts(3,40): error TS2322: Type 'string' is not assignable to type 'number'.
index.ts(5,16): error TS2493: Tuple type '[string, number]' of length '2' has no element at index '2'.

A plain array could never catch the last one: for string[], arr[2] is simply a string that happens to be undefined at runtime.

Named Tuple Elements

Labels document what each position means. They change nothing about the type or how you index it, but editors show them in hovers and signature hints, which makes [number, number] much less mysterious.

type Point = [x: number, y: number];
type Span = [start: number, end: number];
type HttpResult = [status: number, body: string];

function distance([x1, y1]: Point, [x2, y2]: Point): number {
    return Math.hypot(x2 - x1, y2 - y1);
}

const start: Point = [0, 0];
console.log(distance(start, [3, 4])); // 5

const result: HttpResult = [404, "Not Found"];
const [code, text] = result;
console.log(code, text); // 404 Not Found

Since TypeScript 5.2 you can label some positions and leave others unlabeled, as in [first: string, number]. Labels are for readers only: [x: number, y: number] and [number, number] are the same type and assignable to each other.

Optional Elements

A ? after an element type makes that position optional. Optional elements must come after the required ones, and each one widens the length type.

type Rgb = [red: number, green: number, blue: number, alpha?: number];

const solid: Rgb = [255, 128, 0];
const faded: Rgb = [255, 128, 0, 0.5];

function toCss([r, g, b, a = 1]: Rgb): string {
    return `rgba(${r}, ${g}, ${b}, ${a})`;
}

console.log(toCss(solid)); // rgba(255, 128, 0, 1)
console.log(toCss(faded)); // rgba(255, 128, 0, 0.5)

const alpha = faded[3];   // number | undefined
const len = solid.length; // 3 | 4
console.log(alpha, len);  // 0.5 3

Reading an optional element gives T | undefined, so a default in the destructuring pattern (a = 1) or a check is needed before arithmetic.

Rest Elements

A rest element, ...T[], stands for any number of elements of type T. It can be at the end, the start, or the middle, with at most one per tuple.

// A label, then any number of scores
type Row = [name: string, ...scores: number[]];
const rows: Row[] = [["Ada", 90, 85], ["Grace", 77], ["Alan"]];

for (const [name, ...scores] of rows) {
    const avg = scores.length ? scores.reduce((a, b) => a + b, 0) / scores.length : 0;
    console.log(name, scores, avg);
}

// Any number of strings, then a number at the end
type PathAndSize = [...segments: string[], bytes: number];
const file: PathAndSize = ["home", "ada", "notes.txt", 2048];
console.log(file.at(-1)); // 2048

The length of a tuple with a rest element is number, since the size is no longer fixed. What remains fixed is where the typed positions are.

Readonly Tuples and as const

readonly [T, U] removes push, pop, splice and index assignment, which is what a fixed-length value should be. Writing as const after an array literal infers a readonly tuple of literal types.

const pair: readonly [string, number] = ["x", 1];
// @ts-expect-error: Cannot assign to '0' because it is a read-only property.
pair[0] = "y";
console.log(pair); // [ 'y', 1 ]: not frozen at runtime

// as const: a readonly tuple with the exact literal values
const corner = [10, 20] as const; // readonly [10, 20]
const [cx, cy] = corner;          // cx: 10, cy: 20
console.log(cx + cy);             // 30

// Useful for fixed lists of allowed values
const SIZES = ["small", "medium", "large"] as const;
type Size = (typeof SIZES)[number]; // "small" | "medium" | "large"
const pick: Size = "medium";
console.log(SIZES.length, pick);   // 3 medium

(typeof SIZES)[number] turns the tuple into a union of its element types, a pattern covered on indexed access types. A readonly tuple cannot be passed to a parameter typed as a mutable tuple, so functions that only read should accept readonly [number, number].

The readonly check is compile-time only. At runtime the array is not frozen (the assignment above really ran, as the output shows), so use Object.freeze if you need a runtime guarantee.

Returning a Tuple from a Function

Returning several values as a tuple is how React's useState works (const [value, setValue] = useState(0)). The catch: an array literal in a return is inferred as an array, not a tuple.

// This does not compile: the return type was inferred as an array.
function useCounter(start: number) {
    let count = start;
    const increment = () => ++count;
    return [count, increment];
}

const [count, increment] = useCounter(10);
console.log(count + 1);
increment();

index.ts(9,13): error TS2365: Operator '+' cannot be applied to types 'number | (() => number)' and 'number'.
index.ts(10,1): error TS2349: This expression is not callable.
  Not all constituents of type 'number | (() => number)' are callable.
    Type 'number' has no call signatures.

The function returns (number | (() => number))[], so both destructured names get the union type. There are two fixes: annotate the return type, or add as const.

// Fix 1: annotate the return type as a tuple
function useCounter(start: number): [number, () => number] {
    let count = start;
    return [count, () => ++count];
}

// Fix 2: as const infers readonly [boolean, () => boolean]
function useToggle(initial: boolean) {
    let on = initial;
    return [on, () => (on = !on)] as const;
}

const [count, increment] = useCounter(10);
console.log(count + 1, increment()); // 11 11

const [on, toggle] = useToggle(false);
console.log(on, toggle(), toggle()); // false true false

A tuple return value lets callers name the parts whatever they like. When there are more than two or three values, or the order is not obvious, return an object instead: { count, increment } documents itself.

Tuples as Function Parameters

A rest parameter typed as a tuple describes a whole argument list, including optional arguments. This is how the built-in Parameters<T> utility type represents a function's parameters.

function greet(...args: [name: string, times?: number]) {
    const [name, times = 1] = args;
    console.log(Array(times).fill(`Hi ${name}`).join(", "));
}

greet("Ada");     // Hi Ada
greet("Ada", 2);  // Hi Ada, Hi Ada

type GreetArgs = Parameters<typeof greet>; // [name: string, times?: number | undefined]
const saved: GreetArgs = ["Grace", 3];
greet(...saved); // Hi Grace, Hi Grace, Hi Grace

Spreading a tuple into a call type-checks each argument by position, which a spread of (string | number)[] could not.

Tuple vs Array

Tuples also show up in built-in types. Object.entries(obj) returns [string, T][], and a Map is constructed from [key, value] tuples:

const stock = { apples: 3, pears: 0 };

for (const [fruit, qty] of Object.entries(stock)) { // [string, number]
    console.log(fruit, qty > 0 ? "in stock" : "sold out");
}

const prices = new Map<string, number>([["tea", 2.5], ["coffee", 3.2]]);
const entries: [string, number][] = [...prices];
console.log(entries); // [ [ 'tea', 2.5 ], [ 'coffee', 3.2 ] ]

One trap: a mutable tuple still has every array method, so pair.push(3) compiles on a [string, number] and quietly makes a three-element array whose type says two. Declaring tuples readonly closes that hole. And since types are erased, data from outside the program (JSON, an API) is not checked against a tuple type at runtime: validate its length and element types before trusting it.

Variadic Tuple Types

Tuple types can spread other tuple types, [...T, ...U]. Combined with generics, this types functions that concatenate or prepend while keeping every position:

function concat<T extends unknown[], U extends unknown[]>(a: [...T], b: [...U]): [...T, ...U] {
    return [...a, ...b];
}

const joined = concat([1, "a"], [true]); // [number, string, boolean]
const [num, str, flag] = joined;
console.log(num.toFixed(1), str.toUpperCase(), !flag); // 1.0 A false

type WithId<T extends unknown[]> = [id: number, ...rest: T];
const row: WithId<[string, boolean]> = [7, "Ada", true];
console.log(row);

Library types lean on tuple inference too: Promise.all([fetchUser(), fetchPosts()]) resolves to a tuple with one type per input promise.