Tuples in TypeScript Explained

TypeScript tuples are arrays with a known, fixed length where each position has its own type. An array of strings means "any number of strings." A tuple of two elements, a string followed by a number, means "exactly two elements: a string at index 0 and a number at index 1."

TypeScript tuples let you model small, position-based groups of data without defining a named interface or type alias for every one-off case. They are the type system's way of saying "this array has a specific shape at specific indexes."

Writing a tuple type

A tuple type is written with square brackets containing the type at each position, separated by commas. The order of types matters -- swapping the first and second type creates an entirely different tuple. Here is a two-element tuple where the first position is a string and the second is a number, along with how you read values from each position:

typescript

let pair: [string, number] = ["hello", 42];
 
let word = pair[0];
let count = pair[1];

At index 0, TypeScript expects a string value, and at index 1, it expects a number value. When you read those indices, TypeScript gives you precisely those types without any union or narrowing.

TypeScript infers word as a string and count as a number, so you can call string methods on the first element and number methods on the second immediately. No type guard is needed because the tuple guarantees what lives at each position.

This is the key difference from a union array, where you must narrow before using member-specific methods. Each index position in the tuple has its own independent type that stays fixed no matter how you access it.

The compiler also blocks assignments that put the wrong type at a position. Here the string and number values are swapped compared to the tuple's declared order, so both positions now hold the wrong type:

typescript

let pair: [string, number] = [42, "hello"];

TypeScript checks each position independently and reports both mismatches at once, one error for each position that does not match the declared type:

text

Type 'number' is not assignable to type 'string'.
Type 'string' is not assignable to type 'number'.

The error pinpoints both positions individually, so you can see exactly which index needs to change.

How tuples differ from arrays

A regular array has one element type repeated for every element and an unknown length. You can access any index and TypeScript assumes the element type is present, even if the array is shorter at runtime.

A tuple has per-position types and a known, fixed length. Accessing an index beyond the tuple's declared length is a compiler error. This catches out-of-bounds access that would silently return undefined in plain JavaScript.

typescript

let pair: [string, number] = ["hello", 42];
 
let c = pair[2];

Trying to access index 2 on a two-element tuple produces a compiler error instead of silently returning undefined at runtime. The compiler tells you exactly which tuple type is involved and which index is out of bounds:

text

Tuple type '[string, number]' of length '2' has no element at index '2'.

The length property of a tuple is also typed as a literal number, not the broad number type. For a two-element tuple, the length is typed as exactly 2. This means TypeScript can reason about the exact size of the tuple throughout your code.

Destructuring tuples

JavaScript array destructuring works with tuples and preserves the per-position types for each variable. Each destructured variable gets exactly the type from its source position, so there is no extra annotation to write.

typescript

let pair: [string, number] = ["hello", 42];
 
let [word, count] = pair;

After destructuring, word has type string and count has type number. You can call string methods on word and number methods on count without any additional checks.

This is why tuples pair naturally with patterns like React's useState, where the return type of state value and setter function is a two-element tuple. Destructuring that return value gives you a correctly typed state variable and a correctly typed setter function in one line.

Labeled tuples

TypeScript lets you add labels to tuple elements for documentation purposes. Labels do not change the type at all -- they are erased at compile time -- but they make the intent clearer in editor tooltips when you hover over an element.

typescript

type HttpResult = [status: number, body: string];
 
let result: HttpResult = [200, "OK"];

When you hover over result[0] in your editor, the tooltip shows "status: number" instead of just "number." The labels are purely for readability and have no effect on the compiled JavaScript or the type-checking behaviour.

Labels also make destructuring easier to review, since a reviewer can see status and body in the type definition instead of guessing what each position means from usage alone.

When to use tuples vs objects

Tuples work well when the position-based meaning is obvious and the group is small. Objects work better when property names are needed for clarity or when the group has many fields.

Tuples trade named clarity for brevity. If you find yourself wondering what index 2 was supposed to mean, switch to an object or at least add labels. For data with more than three positional fields, objects are almost always the better choice.

Drawbacks of tuples

Labels on tuple elements are invisible at runtime. If another developer reads the code without an editor that shows tooltips, the meaning of each index position is lost. Consider this when choosing between tuples and objects for shared code.

The push method still works on plain tuples because a tuple is an array at runtime. After pushing an extra element, the type system does not know about it, creating a gap between what TypeScript thinks the array contains and what it actually contains.

Use readonly tuples to block this. For more flexible tuple patterns, see optional tuple elements in TypeScript and variadic tuples in TypeScript.