Ramda’s R.lens() answers a focus question: how do I get and set one field without rewriting the rest of the object every time? You pass a getter (read the focus) and a setter (put a new focus back). You get a lens. Then R.view reads, R.set replaces, and R.over maps a function over that one part.
The official sample is the whole idea. R.lens(R.prop('x'), R.assoc('x')) focuses the x field. View returns 1. Set returns a new point with x: 4. Over with R.negate returns x: -1. The original object is not mutated when the setter is R.assoc. Need a property name only? That is R.lensProp. Need an array index? That is the next helper, R.lensIndex. Need a nested path? That is R.lensPath.
Syntax
Call R.lens. Start with this line.
Ramda
R.lens(getter, setter)
Call
What it does
R.lens(getter, setter)
Primary signature.
R.lens(...)
Call the object helper.
Prefer import { lens } from "ramda" when you want a named import.
Library declarations
Ramda
R.lens(getter, setter)
Parameters
Parameter
Description
getter
Required. Function. Given the whole structure s, return the focused value a. Official: R.prop('x').
setter
Required. Function. Given a new focus a and the original structure s, return a new structure. Official: R.assoc('x'). Must not mutate.
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 x lens with view, set, and over, then the same focus as lensProp.
R.over(xLens, R.inc) waits for the object. R.view(xLens) waits for the object. Drop them into R.pipe when you need a longer chain.
Compatibility
Browser Support
R.lens() 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.lens()
Load Ramda 0.8.0 or later via CDN or npm, then call R.lens with a getter and a setter. 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.lens()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.lens(getter, setter) returns a lens: a reusable focus on one part of a structure. R.view reads the focus. R.set replaces it. R.over maps a function over it. The setter must not mutate the original. Added in v0.8.0.
lens is the general constructor: you pass any getter and setter. lensProp('x') is the same as lens(prop('x'), assoc('x')). lensIndex(0) focuses one array index. Use the shortcuts when they fit; use lens for custom get/set pairs.
No, when the setter is immutable (assoc, update, and the built-in lens helpers). The docs say the setter should not mutate the data structure. The original point still has x: 1 after you set x to 4.
The getter is s to a: given the whole structure, return the focused value. The setter is (a, s) to s: given a new focused value and the original structure, return a new structure. Ramda then wires those two into view, set, and over.
No. R.lens is a stable Ramda object helper from v0.8.0. It is not deprecated, experimental, or non-standard.