TypeScript Tuples - Syntax and Examples

TypeScript Tuples: Syntax and Examples

A TypeScript tuple is an array type that describes a fixed sequence of elements. Each position can have its own type, so a tuple such as [string, number] requires a string at index 0 and a number at index 1.

Tuples are useful when the position of each value has a defined meaning. Common examples include coordinate pairs, function return values, database rows, and compact key-value entries. They have some conceptual similarity to structures in C, but tuple members are identified by position rather than by object property names.

This tutorial covers typed tuple declarations, indexed access, destructuring, updates, named and readonly tuples, optional and rest elements, tuple return types, generic tuples, and arrays of tuples.

Declare and initialize a TypeScript tuple
Access and destructure tuple elements
Update mutable tuple elements
Clear or replace tuple values safely

TypeScript Tuple Syntax

A tuple type is written inside square brackets, with the type of each position listed in order.

</>

Copy

let tupleName: [Type1, Type2, Type3] = [value1, value2, value3];

For example, the following tuple must contain a student name, age, and school in that order:

</>

Copy

let student: [string, number, string] = ["Roshan", 15, "AB School"];

console.log(student[0]); // Roshan
console.log(student[1]); // 15
console.log(student[2]); // AB School

Tuple indexes start at 0. TypeScript checks both the type assigned to each declared position and, for a fixed tuple, the required number of elements.

An array literal is not automatically treated as a tuple in every context. For example, let value = ["Roshan", 15] is normally inferred as (string | number)[]. Add an explicit tuple annotation or use an appropriate as const assertion when fixed positions matter.

Declare and Initialize a TypeScript Tuple

The clearest way to create a mutable tuple is to provide its tuple type when declaring the variable.

</>

Copy

let student: [string, number, string];
student = ["Roshan", 15, "AB School"];

The following original syntax example shows an array literal without a tuple annotation. In current TypeScript, it is generally inferred as an array rather than a fixed tuple:

</>

Copy

 var tuple_name = [field1, field2, .., fieldn]

The values are separated by commas and enclosed in square brackets. To make the intended tuple contract explicit, add a type such as [string, number, string].

The following original example likewise creates an inferred array unless a tuple annotation is added:

var student1 = [“Roshan”, 15, “AB School”]

The intended positions are the student’s name, age, and school. A typed declaration for that data is let student1: [string, number, string] = ["Roshan", 15, "AB School"];.

The next retained example builds an initially empty array by assigning values at indexes. It does not establish a fixed tuple type and should not be used when compile-time tuple checking is required.

example.ts

</>

Copy

var student1 = []

student1[0] = "Roshan"
student1[1] = 15
student1[2] = "AB School"

For a genuine tuple, declare the complete type first and then assign a value containing all required elements.

Access TypeScript Tuple Elements by Index

Use a zero-based numeric index to read an element. With an explicitly typed tuple, TypeScript knows the type at each position.

</>

Copy

const student: [string, number, string] = ["Roshan", 15, "AB School"];

const studentName = student[0]; // string
const age = student[1];         // number
const school = student[2];      // string

console.log(`${studentName} is ${age} and studies at ${school}.`);

The following retained example demonstrates indexed access. Because it omits a tuple annotation, its elements are inferred from a union array type rather than from fixed positional types.

example.ts

</>

Copy

var student1 = ["Roshan", 15, "AB School"]

console.log("Name of the student is : "+student1[0])
console.log("Age of the student is : "+student1[1])
console.log(student1[0]+" is studying in "+student1[1])

Output

Name of the student is : Roshan
Age of the student is : 15
Roshan is studying in AB School

The final expression in the retained source accesses student1[1], although the displayed output refers to the school. Use index 2 to read "AB School".

Destructure a TypeScript Tuple into Variables

Tuple destructuring assigns positional elements to separate variables. When the source has a tuple type, each variable receives the type associated with its position.

</>

Copy

const student: [string, number, string] = ["Roshan", 15, "AB School"];
const [studentName, age, school] = student;

console.log(`Name of the student is: ${studentName}`);
console.log(`Age of the student is: ${age}`);
console.log(`${studentName} is studying at ${school}`);

The same destructuring pattern appears in this original example:

example.ts

</>

Copy

var student1 = ["Roshan", 15, "AB School"]

var [student_name, age, school] = student1

console.log("Name of the student is : "+student_name)
console.log("Age of the student is : "+age)
console.log(student_name+" is studying in "+school)

Update Elements in a Mutable TypeScript Tuple

An element in a mutable tuple can be replaced through its index, but the new value must match the type declared for that position.

</>

Copy

let student: [string, number, string] = ["Roshan", 15, "AB School"];

student[1] = 16;          // Valid: index 1 requires a number
student[2] = "CD School"; // Valid: index 2 requires a string

// student[1] = "sixteen"; // Error: string is not assignable to number

The following original example updates the value at index 1. Its final log statement also reads index 1 where the school at index 2 was intended.

example.ts

</>

Copy

var student1 = ["Roshan", 15, "AB School"]

student1[1] = 16

console.log("Name of the student is : "+student1[0])
console.log("Age of the student is : "+student1[1])
console.log(student1[0]+" is studying in "+student1[1])

Output

Name of the student is : Roshan
Age of the student is : 16
Roshan is studying in AB School

Clear or Replace a TypeScript Tuple Safely

A fixed tuple containing required elements cannot be replaced with an empty array without changing its type. For example, a value of type [string, number, string] must retain all three positions.

</>

Copy

let student: [string, number, string] = ["Roshan", 15, "AB School"];

student = ["", 0, ""]; // Reset while preserving the tuple shape
// student = [];       // Type error: three elements are required

If the application genuinely needs either a populated tuple or no value, represent that state explicitly:

</>

Copy

type StudentTuple = [string, number, string];

let student: StudentTuple | undefined = ["Roshan", 15, "AB School"];
student = undefined;

The following retained example works only because student1 is inferred as an array compatible with []. It is not valid for a fixed tuple with three required elements.

example.ts

</>

Copy

var student1 = ["Roshan", 15, "AB School"]
student1 = []

Named Tuple Elements in TypeScript

Named tuple elements document the role of each position without changing the tuple’s runtime representation. The labels improve editor hints and make function signatures easier to read.

</>

Copy

type Student = [name: string, age: number, school: string];

const student: Student = ["Roshan", 15, "AB School"];
const [name, age, school] = student;

The labels do not create properties such as student.name. Values are still accessed with indexes or destructuring. Use an object type when callers need property-based access.

Readonly TypeScript Tuples and as const

Add readonly when tuple positions must not be reassigned. This is useful for constants, coordinates, and function parameters that should not be modified.

</>

Copy

const location: readonly [number, number] = [17.385, 78.487];

// location[0] = 18; // Error: tuple is readonly

A const assertion can infer a readonly tuple containing literal types:

</>

Copy

const statusEntry = [200, "OK"] as const;
// Inferred as: readonly [200, "OK"]

Declaring an array variable with const alone does not make its elements readonly. Use a readonly tuple type or as const when element mutation must be prevented.

Optional and Rest Elements in TypeScript Tuples

An optional tuple element is marked with ?. Optional elements normally follow required elements.

</>

Copy

type UserEntry = [id: number, name: string, email?: string];

const firstUser: UserEntry = [101, "Meera"];
const secondUser: UserEntry = [102, "Arun", "arun@example.com"];

A rest element permits a variable number of trailing values while preserving the types of the leading positions.

</>

Copy

type Command = [name: string, ...arguments: string[]];

const build: Command = ["build", "--production", "--verbose"];
const clean: Command = ["clean"];

Return Multiple Values with a TypeScript Tuple

A function can use a tuple return type when it returns a small, ordered group of values that callers are expected to destructure.

</>

Copy

function divide(dividend: number, divisor: number): [quotient: number, remainder: number] {
    return [Math.trunc(dividend / divisor), dividend % divisor];
}

const [quotient, remainder] = divide(17, 5);
console.log(quotient);  // 3
console.log(remainder); // 2

Use an object return type instead when the values need descriptive property access, when the order is not obvious, or when the return shape is likely to gain several optional fields.

Create an Array of TypeScript Tuples

An array of tuples is useful when every row follows the same positional structure. Place the tuple type inside parentheses when adding array notation.

</>

Copy

const scores: Array<[student: string, score: number]> = [
    ["Roshan", 86],
    ["Meera", 91],
    ["Arun", 78]
];

for (const [student, score] of scores) {
    console.log(`${student}: ${score}`);
}

The equivalent type syntax is [student: string, score: number][].

Generic TypeScript Tuple Examples

Generics can preserve the types of values placed into a reusable tuple. The following function creates a pair without losing the individual types of its arguments:

</>

Copy

function pair<First, Second>(first: First, second: Second): [First, Second] {
    return [first, second];
}

const product = pair("Keyboard", 2499);
// Type: [string, number]

const setting = pair("darkMode", true);
// Type: [string, boolean]

TypeScript Tuple Versus Array Versus Object

Type	Use it when	Example
Tuple	The number, order, and type of positions have defined meanings.	`[number, string]`
Array	The collection contains a variable number of similar items.	`string[]`
Object	Values should be accessed by descriptive property names.	`{ id: number; name: string }`

Tuples work best for short, stable sequences. If readers must remember several index meanings or the structure changes frequently, an object is generally clearer.

Frequently Asked Questions About TypeScript Tuples

How do I declare a tuple in TypeScript?

Add a tuple type annotation containing the positional types, such as let result: [number, string] = [200, "OK"];. Without the annotation, an array literal may be inferred as a regular array.

How do I specify a TypeScript tuple return type?

Place the tuple type after the function parameter list. For example, function getResult(): [number, string] declares that the function returns a number followed by a string.

What is a named tuple in TypeScript?

A named tuple adds labels to positional elements, as in [code: number, message: string]. The labels improve documentation and editor hints but do not create runtime object properties.

How do I create a list of tuples in TypeScript?

Use an array whose element type is a tuple, such as Array<[string, number]> or [string, number][]. Every array item must then follow that positional type definition.

Can a TypeScript tuple contain optional or variable elements?

Yes. Use ? for an optional position, such as [string, number?], or a rest element for variable trailing values, such as [string, ...number[]].

TypeScript Tuple Editorial QA Checklist

Confirm that tuple examples include an explicit tuple annotation or an intentional as const assertion.
Verify that each tuple value matches the declared element order and positional types.
Check that examples distinguish fixed tuples from inferred union arrays.
Confirm that readonly tuple examples do not assign to tuple indexes.
Verify that optional elements and rest elements use valid tuple positions.
Check that tuple return examples destructure values in the same order in which the function returns them.
Prefer an object example when more than a few positions would make index meanings unclear.

Summary of TypeScript Tuple Operations

TypeScript tuples describe ordered values whose positions have known types. Declare the tuple type explicitly, access values by index or destructuring, use named elements to document positions, and add readonly when mutation should be prevented. Optional, rest, generic, return-type, and array-of-tuples patterns cover cases where a basic fixed pair is not enough. Continue with the main TypeScript Tutorial for related TypeScript concepts.

TutorialKart.com

TypeScript Tuples – Syntax and Examples