Ramda’s R.lensPath() answers a nested question: how do I get and set a value deep in an object without rewriting the rest of the tree every time? You pass a path array of keys and indexes. You get a lens. Then R.view reads that value, R.set replaces it, and R.over maps a function over it. The original structure is not mutated.
The official sample is the whole idea. R.lensPath(['x', 0, 'y']) walks into x, then the first array item, then y. View returns 2. Set returns a new tree with that y as 1. Over with R.negate returns -2 in the same slot. Need one own key? That is the next helper, R.lensProp. Need one list index? That is the previous helper, R.lensIndex. Need a one-off write with no view? That is R.assocPath.
Syntax
Call R.lensPath. Start with this line.
Ramda
R.lensPath(path)
Call
What it does
R.lensPath(path)
Primary signature.
R.lensPath(...)
Call the object helper.
Prefer import { lensPath } from "ramda" when you want a named import.
Library declarations
Ramda
R.lensPath(path)
Parameters
Parameter
Description
path
Required. Array. The trail to focus. Each step is a string key, an integer index, or a symbol. Official: ['x', 0, 'y'].
Return Value
Return Value
Description
Lens
A focus you pass to R.view, R.set, and R.over. You rarely call the lens function yourself.
Ramda Examples
📚 Getting Started
The official mixed path with view, set, and over, then a one-key path next to lensProp.
Example 1 — Official Mixed Path
Walk x, then index 0, then y. The sibling z and the second item stay put.
That is assocPath creating intermediate objects. R.lensIndex does the opposite on a missing index: set returns the original list. Do not expect both helpers to grow structures the same way.
Example 5 — over with Curry
Bump a nested age, then read it. Both helpers are data-last.
R.over(ageLens, R.inc) waits for the object. R.view(ageLens) waits for the object. Drop them into R.pipe when you need a longer chain.
Compatibility
Browser Support
R.lensPath() is ordinary JavaScript once Ramda is loaded. Logos use the shared browser-image-sprite.png sprite from this project.
✓ Ramda 0.19.0+ · Any JS runtime
Ramda.js R.lensPath()
Load Ramda 0.19.0 or later via CDN or npm, then call R.lensPath with a path array. No extra browser API is required.
100%With Ramda 0.19.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.lensPath()Universal
Bottom line: Safe in any project that includes Ramda 0.19.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.lensPath(path) returns a lens whose focus is a nested trail of keys and indexes. R.view reads that value. R.set replaces it. R.over maps a function over it. Added in v0.19.0. The original structure is not mutated.
const xHeadYLens = R.lensPath(['x', 0, 'y']). On {x: [{y: 2, z: 3}, {y: 4, z: 5}]}, view is 2, set 1 is {x: [{y: 1, z: 3}, {y: 4, z: 5}]}, and over negate is {x: [{y: -2, z: 3}, {y: 4, z: 5}]}.
lensProp focuses one own key. lensIndex focuses one list index. lensPath walks a trail that can mix both, such as ['x', 0, 'y']. A one-key path matches lensProp. A one-index path matches lensIndex.
R.view returns undefined, the same as R.path. R.set builds the nested objects with R.assocPath, so an empty {} can become {user: {name: 'Ada'}}. That is different from lensIndex, which does not grow a list.
The source is R.lens with getter path(p) and setter assocPath(p). view matches path. set matches assocPath. over maps, then assocPath writes the result back.
No. R.lensPath is a stable Ramda object helper from v0.19.0. It is not deprecated, experimental, or non-standard.