Ramda.js R.flatten() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
List

Definition

A helper that pulls every item out of a list and all of its nested arrays, at any depth, and returns them in one new flat array. The order is depth-first, left to right, and the original list is never changed. It has been part of Ramda List since v0.1.0 (stable, not deprecated, experimental, or non-standard).

Why not the native method? Array.prototype.flat() only removes one level unless you pass Infinity, and it needs ES2019. R.flatten always goes all the way down, and it is a plain one-argument function that fits straight into R.pipe.

Syntax

Call R.flatten. Start with this line.

Ramda
R.flatten(list)
CallWhat it does
R.flatten(list)Primary signature.
R.flatten(...)Call the list helper.

Prefer import { flatten } from "ramda" when you want a named import.

Library declarations
Ramda
R.flatten(list)

Parameters

ParameterDescription
listRequired. An array whose items may be arrays, nested to any depth

Return Value

Return ValueDescription
*A new array with no nested arrays left in it

Ramda Examples

Example 1 — Official Deep Flatten

Arrays nested several levels deep come out as one flat list.

Ramda
const nested = [1, 2, [3, 4], 5, [6, [7, 8, [9, [10, 11], 12]]]];

console.log(R.flatten(nested));
// → [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
Try It Yourself

How It Works

  1. Plain items. 1, 2, and 5 are not arrays, so they are copied as they are.
  2. Arrays are opened. [3, 4] is replaced by its items 3 and 4.
  3. Any depth. Inner arrays like [10, 11] are opened too, no matter how deep they sit.
  4. New array. The order is kept left to right, and nested itself is unchanged.

Example 2 — flatten vs unnest

One removes every level. The other removes just one.

Ramda
const data = [[1, [2]], [3]];

console.log(R.unnest(data));
// → [1, [2], 3]

console.log(R.flatten(data));
// → [1, 2, 3]
Try It Yourself

How It Works

  1. Two levels. data holds arrays, and one of them holds another array, [2].
  2. unnest. R.unnest opens the outer arrays only, so [2] survives.
  3. flatten. It keeps going and opens [2] as well.
  4. Choose. Use unnest when inner arrays carry meaning, such as pairs, and flatten when you want plain values.

Example 3 — Collect Items From Paged Results

Merge the item lists from several API pages into one list.

Ramda
const pages = [
  { page: 1, items: ["a", "b"] },
  { page: 2, items: ["c"] },
  { page: 3, items: [] }
];

console.log(R.flatten(R.pluck("items", pages)));
// → ["a", "b", "c"]
Try It Yourself

How It Works

  1. Pluck. R.pluck("items", pages) gives [["a", "b"], ["c"], []].
  2. Flatten. Each inner list is opened and its items are copied in order.
  3. Empty pages vanish. Page 3’s [] adds nothing.
  4. Tip. R.chain(R.prop("items"), pages) does the pluck and a one-level flatten in a single pass.

Example 4 — Sum Every Cell of a Matrix

Flatten a 2D grid so list helpers can work on all of its values.

Ramda
const matrix = [
  [1, 2],
  [3, 4],
  [5, 6]
];

const cells = R.flatten(matrix);
console.log(cells);
// → [1, 2, 3, 4, 5, 6]

console.log(R.sum(cells));
// → 21
Try It Yourself

How It Works

  1. Rows to cells. Each row is opened in order, giving the values row by row.
  2. Now it is a plain list. Any list helper works on it, such as sum, uniq, or filter.
  3. Sum. R.sum adds 1 through 6 to get 21.
  4. Grid unchanged. matrix keeps its rows, so you can still use it as a grid.

Example 5 — Flatten in a Pipeline

Turn nested color lists into a unique, readable string. Strings stay whole.

Ramda
const colorList = R.pipe(
  R.flatten,
  R.uniq,
  R.join(", ")
);

const picks = [["red", "blue"], [["red"], "green"]];

console.log(colorList(picks));
// → red, blue, green
Try It Yourself

How It Works

  1. Pass the function. R.flatten appears in R.pipe without parentheses, because pipe calls it later.
  2. Flatten. This gives ["red", "blue", "red", "green"]. The strings are not split into letters.
  3. Unique. R.uniq drops the second "red".
  4. Join. R.join(", ") builds the final string red, blue, green.

Browser & Runtime Support

R.flatten has been a Ramda List helper since v0.1.0. It uses its own recursive loop, so it does not need the ES2019 Array.prototype.flat (Chrome 69+, Firefox 62+, Safari 12+, Node.js 11+). It runs anywhere Ramda runs.

✓ Stable · Ramda 0.1.0+

R.flatten()

Support depends on the Ramda version you load, not on a browser feature. Load it from a CDN or bundler in the browser, or run npm install ramda for Node.js, Bun, and Deno.

100% Modern browsers & runtimes
Google Chrome Modern versions · Desktop & Mobile
Full support
Mozilla Firefox Modern versions · Desktop & Mobile
Full support
Apple Safari Modern versions · macOS & iOS
Full support
Microsoft Edge Chromium-based
Full support
Opera Modern versions
Full support
Samsung Internet Modern versions · Android
Full support
Android WebView Modern WebView
Full support
Internet Explorer Not a target for current Ramda releases
Legacy
Node.js Maintained LTS · npm install ramda
Supported
Bun import from "ramda"
Supported
Deno import from "npm:ramda"
Supported
R.flatten Ramda 0.1.0+

Bottom line: Safe for production in any modern browser or JavaScript runtime once Ramda is loaded, including engines that predate the native flat(). The labs on this page use [email protected] from a CDN.

Frequently Asked Questions

R.flatten(list) returns a new array with every item pulled out of the list and all of its nested arrays, at any depth, in depth-first order. Docs sample: R.flatten([1, 2, [3, 4], 5, [6, [7, 8, [9, [10, 11], 12]]]]) //=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].
R.flatten removes every level of nesting. R.unnest removes exactly one level: R.unnest([[1, [2]], [3]]) is [1, [2], 3], while R.flatten gives [1, 2, 3].
Native arr.flat() removes one level by default; arr.flat(Infinity) removes all of them. R.flatten always goes all the way down, works on engines without ES2019 flat, and is a plain function you can drop into R.pipe.
No. Strings, plain objects, Sets, and Maps inside the list are kept whole. Only arrays and array-like objects (such as arguments or typed arrays) are flattened.
Ramda has no depth argument. Apply R.unnest twice, R.pipe(R.unnest, R.unnest), or use the native arr.flat(2).
No. R.flatten has been part of Ramda since v0.1.0 and is stable. It is not deprecated, experimental, or non-standard.

Next: R.forEach()

Learn how to run a function for every item in a list.

R.forEach() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

6 people found this page helpful