Ramda.js R.chain() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
List

Definition

R.chain(fn, list) runs fn on every item, where fn returns a list, then joins all those lists into one flat list (official Ramda docs). Other libraries call it flatMap. Each item can become zero, one, or many items.

Stable since v0.3.0: R.chain is not deprecated, experimental, or non-standard. It flattens only one level; for full flattening, use R.flatten.

Syntax

Call R.chain. Start with this line.

Ramda
R.chain(fn, list) or R.chain(fn)(list)
CallWhat it does
R.chain(fn, list) or R.chain(fn)(list)Primary signature.
R.chain(...)Call the list helper.

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

Library declarations
Ramda
R.chain(fn, list) or R.chain(fn)(list)

Parameters

ParameterDescription
fnRequired. Turns one item into a list (or another chainable value)
listOptional. The array to walk; omit it to get a reusable function

Return Value

Return ValueDescription
*A new array; the input is never changed

Ramda Examples

Example 1 — Official Duplicate

Turn every number into a pair, then get one flat list — the main sample from the Ramda docs.

Ramda
const duplicate = (n) => [n, n];

console.log(R.chain(duplicate, [1, 2, 3]));
// [1, 1, 2, 2, 3, 3]
Try It Yourself

How It Works

  1. Map. duplicate runs on each number: 1 → [1, 1], 2 → [2, 2], 3 → [3, 3].
  2. Flatten. R.chain joins those three pairs in order.
  3. Result. Three inputs become six numbers in one list.
  4. Unchanged input. The original [1, 2, 3] is not modified.

Example 2 — R.chain vs R.map

Same function, two results: map keeps the pairs nested, chain flattens them.

Ramda
const duplicate = (n) => [n, n];
const nums = [1, 2, 3];

console.log(R.map(duplicate, nums));            // [[1, 1], [2, 2], [3, 3]]
console.log(R.chain(duplicate, nums));          // [1, 1, 2, 2, 3, 3]
console.log(R.unnest(R.map(duplicate, nums)));  // [1, 1, 2, 2, 3, 3]
Try It Yourself

How It Works

  1. map nests. R.map keeps exactly what duplicate returns, so you get a list of lists.
  2. chain flattens. R.chain does the same mapping, then joins the inner lists.
  3. Same thing, two steps. R.unnest after R.map gives the identical result.
  4. Rule of thumb. Want groups? Use map. Want one list? Use chain.

Example 3 — Split Sentences into Words

Each sentence becomes a list of words; chain gives one word list.

Ramda
const toWords = R.chain(R.split(' '));

console.log(toWords(['learn ramda', 'today']));
// ['learn', 'ramda', 'today']
Try It Yourself

How It Works

  1. Curried. R.chain(R.split(' ')) has no list yet, so it returns a reusable function, toWords.
  2. Map. R.split(' ') turns 'learn ramda' into ['learn', 'ramda'] and 'today' into ['today'].
  3. Flatten. The two word lists are joined into ['learn', 'ramda', 'today'].
  4. Point-free. toWords never names its argument, so it drops straight into a pipeline.

Example 4 — Collect Nested Tags

Pull every tag out of a list of users into one list, even when some users have none.

Ramda
const users = [
  { name: 'Ana', tags: ['js', 'css'] },
  { name: 'Ben', tags: [] },
  { name: 'Cy',  tags: ['js'] }
];

console.log(R.chain(R.prop('tags'), users));
// ['js', 'css', 'js']
Try It Yourself

How It Works

  1. Map. R.prop('tags') reads each user’s tag array: ['js', 'css'], [], ['js'].
  2. Empty is fine. Ben’s [] adds nothing when the lists are joined.
  3. Flatten. The result is one list of all tags, in user order.
  4. Duplicates stay. 'js' appears twice; add R.uniq if you need unique tags.

Example 5 — Official Append the Head

When the second argument is a function, R.chain(f, g)(x) means f(g(x), x).

Ramda
const appendHead = R.chain(R.append, R.head);

console.log(appendHead([1, 2, 3]));
// [1, 2, 3, 1]
Try It Yourself

How It Works

  1. g runs first. R.head([1, 2, 3]) gives 1.
  2. f gets both. R.append(1, [1, 2, 3]) receives the head and the original list.
  3. Result. 1 is added to the end: [1, 2, 3, 1].
  4. Not a loop. This form runs once on the whole value; it does not visit each item.

Browser & Runtime Support

R.chain() is plain JavaScript inside Ramda 0.3.0+. It does not use native Array.prototype.flatMap (ES2019), so support depends only on loading Ramda.

✓ Ramda 0.3.0+ · Any JS runtime

Ramda.js R.chain()

The UMD build (ramda.min.js) is compiled to ES5 syntax, so it runs in Chrome, Firefox, Safari, and Edge. Via npm it works in Node.js, Deno, and Bun with require or import.

100% With Ramda 0.3+ loaded
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
R.chain() Universal

Bottom line: Safe in any project with Ramda 0.3.0 or later (check with npm ls ramda). Load ramda.min.js from a CDN in the browser, or npm install ramda for Node, Deno, and Bun. These labs load [email protected].

Frequently Asked Questions

R.chain(fn, list) runs fn on every item, where fn returns a list, then joins all those lists into one flat list. The official sample R.chain(n => [n, n], [1, 2, 3]) returns [1, 1, 2, 2, 3, 3]. Other libraries call this flatMap.
Both call fn on every item. R.map keeps whatever fn returns, so lists stay nested: [[1, 1], [2, 2], [3, 3]]. R.chain flattens one level, giving [1, 1, 2, 2, 3, 3]. R.chain(fn, list) equals R.unnest(R.map(fn, list)).
For arrays, yes: both map and then flatten one level. R.chain is curried and data-last, so R.chain(fn) is a reusable function for R.pipe. It also dispatches to chain methods on other types and works as a transducer.
Return an empty array for that item. Empty lists add nothing when the results are joined, so R.chain(n => n % 2 === 0 ? [n * 10] : [], [1, 2, 3, 4]) returns [20, 40].
When the second argument is a function, R.chain(f, g)(x) is f(g(x), x). The official sample R.chain(R.append, R.head)([1, 2, 3]) appends the head 1 to the same list and returns [1, 2, 3, 1]. f must be curried, such as a Ramda function.
No. R.chain has been a stable Ramda list function since v0.3.0. It is not deprecated, experimental, or non-standard.

Next: R.collectBy()

Split a list into groups based on a key function.

R.collectBy() 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