Ramda’s R.assoc() answers a simple question: give me a copy of this object with one property set. You pass the key, then the value, then the object. You get a new object. The original is never mutated. If the key is new, it is added. If it already exists, the clone holds the new value.
The official sample is the whole idea. R.assoc('c', 3, {a: 1, b: 2}) is {a: 1, b: 2, c: 3}. Native JavaScript’s cousin is { ...obj, c: 3 } or Object.assign({}, obj, { c: 3 }). Those are data-first. assoc is data-last, so R.assoc('c', 3) is already a function of one object — ready for R.map or R.pipe. Need a nested key? That is R.assocPath. Need to drop a key? That is R.dissoc. Lodash _.set writes in place; Ramda clones.
Syntax
Call R.assoc. Start with this line.
Ramda
R.assoc(prop, val, obj)
Call
What it does
R.assoc(prop, val, obj)
Primary signature.
R.assoc(...)
Call the object helper.
Prefer import { assoc } from "ramda" when you want a named import.
Library declarations
Ramda
R.assoc(prop, val, obj)
Parameters
Parameter
Description
prop
Required. String or Int. The property name to set. An integer key on an array replaces that index on a new array.
val
Required. Any. The value stored at prop on the clone.
obj
Required. Object or Array. The source. It is never mutated. A new object (or array) is returned.
Return Value
Return Value
Description
Object or Array
A shallow clone with prop set to val. Enumerable own properties (and enumerable prototype properties) are copied onto the new object. Nested objects stay shared by reference.
Ramda Examples
📚 Getting Started
The official Ramda sample, then the same object with an overwritten key so add vs replace is obvious.
Example 1 — Official Object
A new key is added on a clone. The leftover is every original property plus c: 3.
Spread and Object.assign are data-first. assoc is data-last, so the key and value can be filled first. dissoc is the docs’ see-also for the opposite edit: drop a property instead of setting one.
Example 4 — Shallow Copy vs assocPath
Nested objects are shared by reference after assoc. Nested updates belong to assocPath, which clones along the path.
assoc copied the user pointer, then added role. Changing withRole.user.name would also change orig.user.name. assocPath clones the user object so name can change on a new tree. That is the next Object helper.
Example 5 — Curry and Arrays
Fill the key and value to get a function of one object. Map it over rows. An integer key on an array replaces that index on a new array.
Because assoc is arity 3, filling prop and val leaves a function of one object, ready for R.map and R.pipe. Integer keys on arrays go through the array branch: a new array, same values, one index replaced. For a function of the old value, List R.update and R.adjust are the named cousins.
Compatibility
Browser Support
R.assoc() is ordinary JavaScript once Ramda is loaded. Logos use the shared browser-image-sprite.png sprite from this project.
✓ Ramda 0.8.0+ · Any JS runtime
Ramda.js R.assoc()
Load Ramda 0.8.0 or later via CDN or npm, then call R.assoc with a key, a value, and an object. No extra browser API is required.
100%With Ramda 0.8.0+
Google ChromeAll versions · Desktop & Mobile
Full support
Mozilla FirefoxAll versions · Desktop & Mobile
Full support
Apple SafariAll versions · macOS & iOS
Full support
Microsoft EdgeAll versions · Chromium & Legacy
Full support
Internet ExplorerIE 6+ · Legacy environments
Full support
OperaAll modern versions
Full support
R.assoc()Universal
Bottom line: Safe in any project that includes Ramda 0.8.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.assoc(prop, val, obj) returns a shallow clone of obj with prop set to val. If the key is new, it is added. If it already exists, it is overwritten. Added in v0.8.0. The original object is not mutated.
R.assoc('c', 3, {a: 1, b: 2}) is {a: 1, b: 2, c: 3}. The new object has every original property plus c: 3.
No. It always returns a new object (or a new array when prop is an integer and obj is an array). Nested objects and arrays are copied by reference, so the clone is shallow.
assoc sets one top-level key. assocPath sets a nested path such as ['user', 'name']. dissoc removes a key on a clone. The docs also point to R.pick for keeping only some keys.
{ ...obj, c: 3 } is the native cousin. assoc is curried and data-last, so R.assoc('c', 3) is already a function of one object. Spread is data-first and not reusable in R.map without a wrapper.
No. R.assoc is a stable Ramda object helper from v0.8.0. It is not deprecated, experimental, or non-standard.