Ramda.js R.unwind() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Object

Definition

Ramda’s R.unwind() answers a row-explode question: if this object has an array on one key, can I get one copy of the object for each item? You pass a key and an object. You get a list of new objects. Only that key is replaced. Other fields, including other arrays, stay as they are.

The official sample is the whole idea. Alice has two hobbies. R.unwind('hobbies', alice) returns two records: one with hobbies: 'Golf' and one with hobbies: 'Hacking'. colors is still ['red', 'green'] on both. The docs wording comes from MongoDB’s $unwind: deconstruct an array field into one document per element. Native JavaScript is a map plus a shallow copy. Need a named copy of one field? That is R.assoc. Previous Object helper is R.toPairsIn.

Syntax

Call R.unwind. Start with this line.

Ramda
R.unwind(key, object)
CallWhat it does
R.unwind(key, object)Primary signature.
R.unwind(...)Call the object helper.

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

Library declarations
Ramda
R.unwind(key, object)

Parameters

ParameterDescription
keyRequired. String. The property to explode. Only this name is replaced on each leftover object.
objectRequired. Object. The record that may hold an array at key. null throws because the source uses the in operator.

Return Value

Return ValueDescription
Array of objectsOne shallow copy per item when object[key] is an array. Empty array → []. Missing key or non-array → [object]. The source object is not mutated.

Ramda Examples

📚 Getting Started

The official alice sample, then the easy mix-up between a missing key and an empty array.

Example 1 — Official Hobbies Unwind

One array field becomes one object per item. Sibling arrays stay arrays.

Ramda
const alice = {
  name: 'alice',
  hobbies: ['Golf', 'Hacking'],
  colors: ['red', 'green']
};

R.unwind('hobbies', alice);
//=> [
//     { name: 'alice', hobbies: 'Golf', colors: ['red', 'green'] },
//     { name: 'alice', hobbies: 'Hacking', colors: ['red', 'green'] }
//   ]
Try It Yourself

How It Works

That is the docs sample from ramdajs.com. Only hobbies is replaced. colors is still a list on both leftovers. The original alice object is not mutated.

Example 2 — Missing Key vs Empty Array

Missing means wrap the original. Empty means no leftovers at all.

Ramda
R.unwind('hobbies', { name: 'bob' });
//=> [{ name: 'bob' }]

R.unwind('hobbies', { name: 'cara', hobbies: [] });
//=> []
Try It Yourself

How It Works

The source only maps when the leftover is an array. No key means the in check fails, so you get [object]. An empty array still passes that check, so map returns [].

📈 Practical Patterns

Non-array leftovers, a curried mapper, then flatten many documents with chain.

Example 3 — Non-array Leftover

A string at that key is not unwound. The original is wrapped in a one-item list.

Ramda
const already = { name: 'dana', hobbies: 'Golf' };

R.unwind('hobbies', already);
//=> [{ name: 'dana', hobbies: 'Golf' }]

already.hobbies;
//=> 'Golf'
Try It Yourself

How It Works

_isArray is false for a string, so unwind does not copy. The leftover list still holds the same object reference. Do not treat a wrapped original as a new row.

Example 4 — Curry the Key, Then Map

Arity 2 lets you fix the field name and map over a list of people.

Ramda
const byHobby = R.unwind('hobbies');

R.map(byHobby, [
  { name: 'alice', hobbies: ['Golf'] },
  { name: 'bob', hobbies: ['Chess', 'Go'] }
]);
//=> [
//     [{ name: 'alice', hobbies: 'Golf' }],
//     [{ name: 'bob', hobbies: 'Chess' }, { name: 'bob', hobbies: 'Go' }]
//   ]
Try It Yourself

How It Works

R.map keeps one inner list per person. Need a flat table? That is R.chain in the next example.

Example 5 — Flatten Many Documents with Chain

R.chain maps unwind, then concatenates the leftover lists.

Ramda
const people = [
  { name: 'alice', hobbies: ['Golf', 'Hacking'] },
  { name: 'bob', hobbies: ['Chess'] }
];

R.chain(R.unwind('hobbies'), people);
//=> [
//     { name: 'alice', hobbies: 'Golf' },
//     { name: 'alice', hobbies: 'Hacking' },
//     { name: 'bob', hobbies: 'Chess' }
//   ]
Try It Yourself

How It Works

R.chain(fn, list) is map then unnest. Each person becomes one or more rows. A person whose hobbies array is empty contributes nothing to the table.

Browser Support

R.unwind() is ordinary JavaScript once Ramda is loaded. Logos use the shared browser-image-sprite.png sprite from this project.

✓ Ramda 0.28.0+ · Any JS runtime

Ramda.js R.unwind()

Load Ramda 0.28.0 or later via CDN or npm, then call R.unwind with a key and an object. No extra browser API is required.

100% With Ramda 0.28.0+
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
R.unwind() Universal

Bottom line: Safe in any project that includes Ramda 0.28.0 or later. Use a CDN build such as ramda.min.js in the browser or install ramda from npm for Node. These labs use [email protected].

Frequently Asked Questions

R.unwind(key, object) turns one array field into a list of objects. Each leftover object is a shallow copy of the input with that key set to one item from the array. Added in v0.28.0.
R.unwind('hobbies', { name: 'alice', hobbies: ['Golf', 'Hacking'], colors: ['red', 'green'] }) returns two objects: hobbies is 'Golf' on the first and 'Hacking' on the second. colors stays an array on both.
Missing key or a non-array leftover returns [object] — the original wrapped in a one-item list. An empty array returns []. Those two leftovers are easy to mix up.
No. Each leftover is a shallow copy via assoc. Nested arrays and objects are still shared references.
R.unwind('hobbies', null) throws, because the source uses the in operator on the object. Guard nil first.
No. R.unwind is a stable Ramda object helper from v0.28.0. It is not deprecated, experimental, or non-standard.

Continue to R.values()

Learn how to list an object’s own values using Ramda R.values().

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