JavaScript Reference
Array.prototype.flat()
Flatten nested arrays into a new array. Configurable depth.
Last updated: October 2026
Definition: Array.prototype.flat() creates a new array with all sub-array elements concatenated into it recursively up to the specified depth. It does not modify the original array [citation:4].
🎬 Live Example
Five flat patterns. Click any button to see the output.
💡 flat returns a new array. Original is never modified.
Basic Syntax
array.flat(depth)
// depth — optional, default 1
// Returns a new array
// Does NOT mutate the original🎯 Syntax & Parameters
| Parameter | Type | Description |
|---|---|---|
depth | number | How deep to flatten. Default: 1. Use Infinity for full depth. |
Basic One-Level Flatten
const arr = [1, 2, [3, 4]];
arr.flat();
// [1, 2, 3, 4]
// Default depth is 1
[1, 2, [3, 4, [5, 6]]].flat();
// [1, 2, 3, 4, [5, 6]] ← inner staysControl the Depth
const deep = [1, [2, [3, [4, [5]]]]];
deep.flat(); // [1, 2, [3, [4, [5]]]]
deep.flat(2); // [1, 2, 3, [4, [5]]]
deep.flat(3); // [1, 2, 3, 4, [5]]
deep.flat(Infinity); // [1, 2, 3, 4, 5]Pro tip: Use Infinity when you don't know the nesting depth.
Removes Empty Slots
const sparse = [1, , 3, [4, , 6]];
sparse.flat();
// [1, 3, 4, 6] ← empty slots removed
// Same with [1, undefined, 3].flat()
// [1, undefined, 3] ← undefined staysNote: flat removes empty slots (sparse array holes) but keeps explicit undefined values.
Non-Array Elements Are Kept
[1, 2, { a: 3 }, [4]].flat();
// [1, 2, { a: 3 }, 4]
// Objects and primitives are not flattened
// Only arrays are processedReal-World: Flatten API Response
const response = {
groups: [
{ items: [1, 2] },
{ items: [3, 4] },
{ items: [5, 6] }
]
};
const allItems = response.groups
.map(g => g.items)
.flat();
// [1, 2, 3, 4, 5, 6]
// Or use flatMap (one step):
const allItems2 = response.groups
.flatMap(g => g.items);🎯 flat vs flatMap vs concat
| Method | Maps? | Flatten depth |
|---|---|---|
flat | No | Configurable |
flatMap | Yes | Depth 1 only |
concat | No | Depth 1 only |
⚠️ Common Mistakes
- Assuming flat flattens everything. Default depth is 1. Use
Infinityfor full depth. - Thinking flat mutates. It returns a new array; the original is unchanged.
- Confusing flat with flatMap. flat doesn't map; flatMap does both.
- Expecting flat to handle non-arrays. Objects and primitives are kept as-is.
- Using flat in older browsers. flat is ES2019 — check for polyfills if targeting IE.
❓ Frequently Asked Questions
What does Array.flat() do in JavaScript?
Array.flat() creates a new array with all sub-array elements concatenated into it recursively up to the specified depth. It does not modify the original array.
What is the default depth for flat?
The default depth is 1. Calling [1, [2, [3]]].flat() returns [1, 2, [3]]. Pass 2 for deeper, or Infinity to fully flatten.
What is the difference between flat and flatMap?
flat only flattens existing nested arrays. flatMap first maps each element using a function, then flattens the result by depth 1. Use flatMap when you need both operations.
Does flat modify the original array?
No. flat returns a new array and does not modify the original. It is a copying method.
How do I fully flatten a deeply nested array?
Pass Infinity as the depth: arr.flat(Infinity). This recursively flattens to any depth.