TypeScript Reference ยท Primitive and Special Types
TypeScript tuple types
Reference for TypeScript tuple types: fixed positions, optional and rest elements, labels, readonly tuples, destructuring and how they differ from arrays.
A tuple is an array type with a known length where each position has its own type. [string, number] describes a two-element array whose first item is a string and whose second is a number. Tuples are ordinary arrays at runtime; the extra precision exists only in the type system.
They are a good fit for small, positional results: a coordinate pair, a [key, value] entry, or the pair returned by a function like useState-style helpers. When elements have names and many fields, an object type is clearer.
const entry: [string, number] = ["age", 36]; const [key, value] = entry;
Try it
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.
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
type Pair = [string, number]; type Named = [name: string, age: number]; type Maybe = [string, number?]; type Rest = [boolean, ...string[]]; type Lead = [...string[], number]; type RO = readonly [string, number];
| Form | Description |
|---|---|
[A, B] |
Exactly two elements of types A and B. |
[a: A, b: B] |
Same, with labels that appear in tooltips and errors. They do not change assignability. |
[A, B?] |
The last elements may be optional; length becomes 1 | 2. |
[A, ...B[]] |
Rest element: any number of B after the first A. |
readonly [A, B] |
Tuple that cannot be mutated. |
Edge cases:
- The
lengthproperty of a fixed tuple has a literal type (2), so you can narrow on it. - An array literal is inferred as an array, not a tuple. Annotate it, or use
as const, to get a tuple. - Methods like
pushandpopexist on mutable tuples and do not update the length type; preferreadonlytuples if you want to avoid that gap. - Optional elements must come after required ones; with
exactOptionalPropertyTypesthey do not accept an explicitundefined.
Usage notes
- Use for small positional data. Past three or four elements an object with named fields is easier to read.
- Labels are documentation. Either all elements are labeled or none are.
- Variadic tuples.
[...A, ...B]spreads tuple types, which powers typedconcatand function argument manipulation. See Labeled and variadic tuples. - Function parameters.
Parameters<F>returns a tuple, and a rest parameter can be typed with a tuple. - Returning multiple values. Tuples are the idiomatic way to return a pair and let callers rename it when destructuring.
- Compatibility. A tuple is assignable to an array of the union of its element types, but not the other way round.