TypeScript Tuple - How does it work?

Tim Mouskhelichvili
Tim Mouskhelichvili
3 minutes to read

TypeScript adds a few new data types that the developer can use. One of them is the Tuple type.

A Tuple is a type of Array that knows how many elements it contains and at which position is which type.

This article will teach you everything to know about this data type as well as show some of the most common use-cases and tuple operations.

Let's get to it 😎.

typescript tuple

What is a Tuple?

A TypeScript Tuple works very similarly to the array, however:

  1. The length and number of elements of the tuple are fixed.
  2. The position of each type is known.
  3. The types need to be different (or else it would not be a tuple).

Here is an example of a very basic Tuple with 2 elements:

typescripttype NumberString = [ number, string ];

In this example, we have created a new type NumberString which will always contain:

  1. A number at index 0.
  2. A string at index 1.

The TypeScript Tuple data type has no representation at runtime.

P.S. TypeScript offers two utility types that returns tuples (Parameters and ConstructorParameters).

How to access a Tuple element?

Just like with the Array, you can access tuple elements by using indexes.

typescripttype AgeAndName = [ number, string ];

const person: AgeAndName = [ 26, 'Tim' ];
const age = person[0];
const name = person[1];

In this example, we get the person's age and name from the tuple called person.

P.S. If we try to access index 2, we will get a TypeScript error, because this tuple only has 2 elements.

How does destructuring work on a Tuple?

Another way of accessing a Tuple element is to use JavaScript destructuring. By using destructuring, we can unpack values from an array, into single variables.

Here is an example of this:

typescripttype AgeAndName = [ number, string ];

const person: AgeAndName = [ 26, 'Tim' ];
const [ age, name ] = person;

As you can see, in this example, we extract the age and the name from the tuple called person.

How to use optional Tuple elements?

A Tuple can also contain, if needed, optional elements, by using the question mark.

typescripttype AgeFirstLast = [ number, string, string?  ];

const person: AgeFirstLast = [ 26, 'Tim' ];
const person2: AgeFirstLast = [ 26, 'Tim', 'Mousk' ];

In this example, we create two person constants, but one contains a last name and the other one doesn't.

How does the labeled Tuple work?

You can, also, put labels on your Tuple elements. Those labels are purely for documentation purposes. They do not affect the runtime behavior.

typescripttype AgeFirst = [ age: number, firstName: string  ];

const person: AgeFirst = [ 26, 'Tim' ];

Using labels makes your tuple clearer, and easier to understand for other developers.

labeled tuple

When to use a TypeScript Tuple?

In TypeScript, a Tuple has a lot of use-cases.

Here are a few real-life examples of when to use the Tuple.

1. The React useState hook

Did you know, that the React useState returns a tuple? Of course, it seems so obvious now...

javascriptconst [ state, setState ] = useState(initialState);

In this example, we are using destructuring to get the state and setState from the react hook.

2. Promise.all function

The Promise.all function also returns a tuple.

typescriptconst a = async (): Promise<boolean> => {
    return true;
};

const b = async (): Promise<string> => {
    return 'aaa';
};

const [responseA, responseB ] = await Promise.all([ a(), b() ]);

In this example, we are using destructuring to get the responseA and responseB from the Promise.all function.

3. Rest parameters & spread expressions with tuples

You can also use the rest parameters and the spread syntax with tuples.

typescripttype Coordinates = [ x: string, y: number, z: boolean ];
declare function find(...args: Coordinates): string;

Tuple VS Array - What is the difference?

Since the Tuple has similar behavior to the Array it can be hard to know the difference between them.

tuple vs array

Here are all the differences between them.

TupleArray
Number of elementsFixedVariable
Elements typesDifferent TypesSame Type
ReadabilityEasy (especially with labels)-

Final Thoughts

I am sure some of you have previously used the Tuple data type without realizing it was a Tuple, especially if you develop using React. The Tuple is very useful when you need to store data in an array that will not change. You can then pair it with destructuring to access the elements of the Tuple.

I hope you liked the article and you now understand TypeScript a little bit better.

Please share this article with your fellow developers, it will help this website a lot.

Comments (0)
Reply to: