TypeScript Arrays and Tuples
A TypeScript array holds a list of values that all share the same type. A TypeScript tuple holds a fixed number of values, each with its own type. Both are essential for grouping data in real projects, from lists of users to coordinate pairs. Understanding the difference keeps your code safe and readable.
This tutorial covers both syntaxes for arrays, typed array methods, arrays of objects, readonly arrays, and how tuples work with named and optional elements. You will also see the one common trap with tuples at runtime and how to avoid it.
What Is a TypeScript Array?
A TypeScript array is an ordered collection of values of the same type. You declare the element type once, and TypeScript checks every value you add or read from the array. Arrays can grow and shrink at runtime.
Here is a basic example:
const cities: string[] = ["Mumbai", "Delhi", "Pune"];
console.log(cities);
// Output: [ 'Mumbai', 'Delhi', 'Pune' ]
The string[] annotation says every element must be a string. If you tried to push a number, the compiler would reject it.
What Are the Two Array Syntaxes?
TypeScript gives you two ways to write an array type: string[] and Array<string>. They mean the same thing. The shorthand string[] is more common because it is shorter. The long form Array<string> is useful when the element type itself is complex.
const tags: string[] = ["new", "sale"];
const labels: Array<string> = ["featured", "trending"];
console.log(tags, labels);
// Output: [ 'new', 'sale' ] [ 'featured', 'trending' ]
How it works: Both declarations produce an array of strings. The compiler treats them identically. Use string[] for simple types and Array<string> when nesting makes the shorthand hard to read, such as Array<string[]> for an array of string arrays.
How Do Typed Array Methods Work?
Array methods like map, filter, and push keep their type information. TypeScript knows the element type of the array and passes it to the callback, so you get full type safety. This connects to contextual typing from the Type Inference & Annotations tutorial.
const scores: number[] = [45, 78, 92, 60];
const doubled = scores.map((score) => score * 2);
const passed = scores.filter((score) => score >= 60);
scores.push(88);
console.log(doubled);
console.log(passed);
console.log(scores);
// Output: [ 90, 156, 184, 120 ]
// Output: [ 78, 92, 60 ]
// Output: [ 45, 78, 92, 60, 88 ]
How it works: map receives each number and returns a new array of the returned type. filter returns a new array of the same element type. push accepts only a number because scores is number[]. If you wrote scores.push("high"), the compiler would report an error.
How Do You Type an Array of Objects?
Arrays often hold objects. You define the object type once and use it as the array element type. This gives you autocomplete and safety on every property.
type Product = {
name: string;
price: number;
};
const products: Product[] = [
{ name: "Notebook", price: 60 },
{ name: "Pen", price: 15 },
{ name: "Bag", price: 850 },
];
const cheapNames = products
.filter((product) => product.price < 100)
.map((product) => product.name);
console.log(cheapNames);
// Output: [ 'Notebook', 'Pen' ]
How it works: The Product type describes one element. The products array is typed as Product[]. Inside filter and map, the parameter product is contextually typed as Product, so product.price and product.name are known. TypeScript rejects misspelled properties like product.cost.
What Is a readonly Array?
A readonly array is an array you cannot change after creation. TypeScript blocks push, pop, and direct index assignment. Use it when a function should read an array but never modify it.
const colors: readonly string[] = ["red", "green", "blue"];
// colors.push("yellow");
// Error: Property 'push' does not exist on type 'readonly string[]'.
console.log(colors[0]);
// Output: red
How it works: The readonly modifier removes the mutating methods from the type. Reading elements and calling non-mutating methods like map still works. This protects shared data from accidental changes. You can also write ReadonlyArray<string> for the same effect.
What Is a TypeScript Tuple?
A TypeScript tuple is an array with a fixed number of elements, each with a known type at a specific position. Unlike a regular array, the type of element 0 can differ from element 1. Tuples are perfect for returning multiple values from a function.
const person: [string, number] = ["Riya", 28];
console.log(person[0]);
console.log(person[1]);
// Output: Riya
// Output: 28
How it works: The type [string, number] says position 0 is a string and position 1 is a number. Swapping them, such as [28, "Riya"], would produce an error. This is stronger than a plain array of string | number.
What Are Named and Optional Tuple Elements?
You can label tuple positions for readability and mark trailing positions as optional. Named elements do not change runtime behavior; they document intent. Optional elements use ? and must come last.
type Point = [x: number, y: number, z?: number];
const flat: Point = [10, 20];
const space: Point = [10, 20, 30];
console.log(flat);
console.log(space);
// Output: [ 10, 20 ]
// Output: [ 10, 20, 30 ]
How it works: The labels x, y, and z appear in editor tooltips, making the tuple easier to read. The z? marks the third element as optional, so both two-item and three-item tuples are valid. Only trailing elements can be optional.
How Do You Destructure a Tuple?
Destructuring means unpacking a tuple or array into named variables in one line. It is the most common way to use tuple return values.
function getProfile(): [string, number] {
return ["Arjun", 32];
}
const [name, age] = getProfile();
console.log(`${name} is ${age} years old.`);
// Output: Arjun is 32 years old.
How it works: The left side [name, age] reads position 0 into name and position 1 into age. TypeScript knows name is a string and age is a number from the return type. This pattern is used widely in React hooks and utility libraries.
Array vs Tuple: What Is the Difference?
| Feature | Array | Tuple |
|---|---|---|
| Length | Can change | Declared fixed length |
| Element types | All the same | Can differ per position |
| Mutating methods | Available (push, pop) |
Available but discouraged |
| Best for | Lists of similar items | Fixed groups like [key, value] |
| Runtime enforcement | None | None (types vanish) |
Common Mistakes and Best Practices
- Assuming a tuple length is enforced at runtime. Tuples are checked only at compile time. Calling
person.push("extra")may compile in some setups and adds a fourth element at runtime. Treat tuples as fixed by convention, and usereadonlytuples likereadonly [string, number]to block mutation. - Using
Array<string>for simple types. The shorthandstring[]is easier to read. ReserveArray<T>for nested generics whereT[][]becomes confusing. - Declaring empty arrays without a type.
const list = []becomesany[]ornever[]. Always annotate asconst list: string[] = []. - Using a tuple when an object is clearer. Tuples like
[string, number, boolean]lose meaning after two positions. Use an object with named fields when the group has more than two values. - Forgetting
readonlyon shared data. Passing an array to a function that might mutate it can cause bugs elsewhere. Mark itreadonlyso the compiler enforces the contract.
Real-World Example: A Student Report
This example combines a typed array of objects with map and filter, plus a tuple return with destructuring.
type Student = {
name: string;
marks: number;
};
const students: Student[] = [
{ name: "Anaya", marks: 88 },
{ name: "Vikram", marks: 54 },
{ name: "Meera", marks: 91 },
{ name: "Rohit", marks: 67 },
];
function getTopper(list: readonly Student[]): [name: string, marks: number] {
const top = list.reduce((best, current) =>
current.marks > best.marks ? current : best
);
return [top.name, top.marks];
}
const passNames = students
.filter((student) => student.marks >= 60)
.map((student) => student.name);
const [topperName, topperMarks] = getTopper(students);
console.log(passNames);
console.log(`${topperName} scored ${topperMarks}.`);
// Output: [ 'Anaya', 'Meera', 'Rohit' ]
// Output: Meera scored 91.
How it works, line by line. The Student type describes one record. The students array is typed as Student[], so every element is checked. The getTopper function accepts a readonly Student[], which means it promises not to modify the list. Its return type is a named tuple [name: string, marks: number], so callers know exactly what comes back. Inside, reduce walks the list and keeps the student with the highest marks; the callback parameters are contextually typed as Student. The passNames chain filters students with marks of 60 or more, then maps to names. The destructuring line const [topperName, topperMarks] unpacks the tuple. Both console.log calls print the results. If you accidentally returned [top.marks, top.name], the compiler would flag the mismatch with the tuple type.
Summary
- A TypeScript array holds values of one type; use
string[]orArray<string>to annotate it. - Typed methods like
map,filter, andpushkeep type information, so callbacks are checked automatically. - Annotate arrays of objects with a named type for autocomplete and safety.
- Use
readonly string[]to prevent mutation of shared arrays. - A TypeScript tuple has fixed positions with different types; use it for pairs and multi-value returns.
- Named and optional tuple elements improve readability, and destructuring unpacks them cleanly.
Now that you can type lists and fixed groups, continue to the TypeScript Enums tutorial to learn how to define a set of named constants.
Frequently Asked Questions
When should I use a tuple instead of an object?
Use a tuple when the position has a clear, conventional meaning and the group is small, such as [key, value] or [latitude, longitude]. For groups with more than two or three values, or when fields need clear names, use an object. Objects are easier to read and extend without breaking existing code.
Does TypeScript stop me from pushing to a tuple at runtime?
No. Type checking happens only at compile time, and types disappear in the compiled JavaScript. The .push method is still available on the array object at runtime. To prevent changes in your code, declare the tuple as readonly, which removes mutating methods from the type.
What is the difference between readonly string[] and ReadonlyArray?
They mean the same thing. readonly string[] is the shorthand and ReadonlyArray<string> is the long form. Both remove push, pop, and index assignment from the type. Pick one style and use it consistently in your project for readability.
Can a tuple have optional elements in the middle?
No. Optional tuple elements must come after all required elements. For example, [string, number?, boolean?] is valid, but [string, number?, boolean] is not. This rule keeps the type predictable because TypeScript always knows the position of required elements.
Why does TypeScript infer never[] for an empty array?
An empty array has no values to infer from, so TypeScript picks the narrowest possible element type, which is never. You cannot push anything into never[]. Annotate the variable, such as const list: string[] = [], so the type is known from the start.
Practice Exercises
Exercise 1 (Easy): Declare and Use a Typed Array
Create an array of numbers called temperatures with three values. Push one more value and print the array.
Show solution
const temperatures: number[] = [28, 31, 26];
temperatures.push(30);
console.log(temperatures);
// Output: [ 28, 31, 26, 30 ]
The number[] annotation makes push accept only numbers, so adding 30 is valid.
Exercise 2 (Easy): Filter an Array of Objects
Create a typed array of three products with name and price. Use filter to get products under 100 and map to print their names.
Show solution
type Product = { name: string; price: number };
const items: Product[] = [
{ name: "Pen", price: 15 },
{ name: "Bag", price: 850 },
{ name: "Notebook", price: 60 },
];
const cheap = items
.filter((item) => item.price < 100)
.map((item) => item.name);
console.log(cheap);
// Output: [ 'Pen', 'Notebook' ]
The Product[] type gives item full typing inside both callbacks, so item.price and item.name are safe.
Exercise 3 (Medium): Return a Tuple and Destructure It
Write a function minMax that accepts a number[] and returns a tuple [number, number] with the smallest and largest values. Destructure the result.
Show solution
function minMax(values: number[]): [number, number] {
return [Math.min(...values), Math.max(...values)];
}
const [low, high] = minMax([12, 5, 40, 8]);
console.log(low, high);
// Output: 5 40
The tuple return type [number, number] tells callers there are exactly two numbers, and destructuring assigns them to low and high.
Exercise 4 (Challenge): Readonly Tuple and Optional Element
Create a function that accepts a readonly tuple [name: string, age: number, city?: string]. Print the name, age, and city (or "unknown"). Show that pushing to the tuple is blocked.
Show solution
function describePerson(
person: readonly [name: string, age: number, city?: string]
): void {
const [name, age, city] = person;
console.log(`${name}, ${age}, ${city ?? "unknown"}`);
}
const p1: readonly [name: string, age: number, city?: string] = ["Riya", 28];
const p2: readonly [name: string, age: number, city?: string] = ["Arjun", 32, "Delhi"];
describePerson(p1);
describePerson(p2);
// p1.push("extra");
// Error: Property 'push' does not exist on type 'readonly [name: string, age: number, city?: string]'.
// Output: Riya, 28, unknown
// Output: Arjun, 32, Delhi
The readonly tuple removes mutating methods, and the optional city lets the destructuring fall back to "unknown" with ??.
Written by Shaikh Abdul Shahid
A Full-Stack Developer with experience in PHP, Laravel, JavaScript, and React.
Founder of Online Learner, sharing practical knowledge and programming tutorials.
Building and maintaining real-world web applications since 2017.
Your Feedback
Help us improve by sharing your thoughts.
Online Learner helps developers master programming, database concepts, interview preparation, and real-world implementation through structured learning paths.
Quick Links
© 2023 - 2026 OnlineLearner.in | All Rights Reserved.
