Suggest an edit

Improve this article

Refine the answer for “What is a tuple in TypeScript?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## 1. Definition

> A **tuple** is a *fixed-length array*,
> where *each element has a predetermined type and position*.

---

### Example

```javascript
const user: [string, number] = ["Tim", 25];
```

> Here:
>
> - `user[0]` is always `string`,
> - `user[1]` is always `number`,
> - you cannot add a third element.

---

## 2. The difference from an array

| Feature | Array (`T[]`) | Tuple (`[T1, T2, ...]`) |
|---|---|---|
| Length | variable | fixed |
| Element type | the same | can differ |
| Indexes | untyped | each index is strictly typed |
| Common use | lists of same-type data | pairs, triples, function return values |

---

### An example of the differences

```javascript
const arr: string[] = ["a", "b", "c"];
const tuple: [string, number] = ["id", 42];

arr.push("d"); // allowed
tuple.push("oops"); // technically possible, but not recommended (see below)
```

> Before TS 4.0, you could "push" an element into a tuple,
> but modern versions of TypeScript now correctly **disallow push** for fixed tuples.

---

## 3. Typing elements by position

```javascript
const point: [number, number] = [10, 20];
const rgb: [number, number, number] = [255, 128, 0];
const settings: [string, boolean, number] = ["dark", true, 60];
```

> Every element is strictly typed.
> TypeScript will not let you swap the types:

```javascript
const wrong: [number, string] = ["a", 1]; // Error
```

---

## 4. Optional elements in a tuple

You can mark positions as optional with `?`:

```javascript
type Point = [number, number?, number?];

const p1: Point = [10];        // just X
const p2: Point = [10, 20];    // X and Y
const p3: Point = [10, 20, 30]; // X, Y, Z
```

---

## 5. Tuples with rest elements

If part of the tuple can repeat, you can use **rest**:

```javascript
type StringPair = [string, string];
type StringList = [string, ...string[]];

const t1: StringList = ["first"];
const t2: StringList = ["first", "second", "third"];
```

> This is especially useful for function signatures with a variable number of arguments.

---

## 6. Example of using tuples in functions

### A function returns several values:

```javascript
function useCounter(): [number, () => void] {
  let count = 0;
  const increment = () => count++;
  return [count, increment];
}

const [count, increment] = useCounter();
```

> This pattern is often used in React hooks (`useState`, `useReducer`, etc.).

---

## 7. A tuple as a function parameter

```javascript
function logTuple(tuple: [string, number]) {
  console.log(`${tuple[0]} - ${tuple[1]}`);
}

logTuple(["id", 42]);
```

> TypeScript checks both the order and the types of the elements.

---

## 8. Named elements (TS 4.0+)

TypeScript lets you give **names to positions** in a tuple for readability:

```javascript
type UserTuple = [name: string, age: number, isAdmin: boolean];

const user: UserTuple = ["Tim", 25, true];
```

> The names (`name`, `age`, `isAdmin`) do not affect the type,
> but they make the code clearer in the IDE and in hints.

---

## 9. Immutable tuples (readonly tuples)

If you need to prevent elements from being changed:

```javascript
const coords: readonly [number, number] = [10, 20];

coords[0] = 30; // Error
coords.push(5); // Error
```

> This is useful for coordinates, configs, and any data
> that must remain constant.

---

## Summary

| Capability | Example | Description |
|---|---|---|
| Basic tuple | `[string, number]` | Fixed types and length |
| Optional elements | `[number, number?]` | Optional positions |
| Rest elements | `[string, ...string[]]` | A flexible number of trailing elements |
| Named elements | `[x: number, y: number]` | Improves readability |
| Immutable tuple | `readonly [string, number]` | Disallows mutation |

Markdown · drag & drop images · ⌘B / ⌘I shortcuts616 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.