Ramda.js R.lens() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Object

Definition

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)
CallWhat 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

ParameterDescription
getterRequired. Function. Given the whole structure s, return the focused value a. Official: R.prop('x').
setterRequired. 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 ValueDescription
LensA 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.

Example 1 — Official x Lens

Read x, replace x, map x with negate. y stays 2.

Ramda
const xLens = R.lens(R.prop('x'), R.assoc('x'));

R.view(xLens, {x: 1, y: 2});
//=> 1
R.set(xLens, 4, {x: 1, y: 2});
//=> {x: 4, y: 2}
R.over(xLens, R.negate, {x: 1, y: 2});
//=> {x: -1, y: 2}
Try It Yourself

How It Works

R.prop('x') is the getter. R.assoc('x') is the setter. That is the docs sample from ramdajs.com.

Example 2 — vs R.lensProp

Both views return the same x.

Ramda
const xLens = R.lens(R.prop('x'), R.assoc('x'));
const point = {x: 1, y: 2};

R.view(xLens, point);
//=> 1
R.view(R.lensProp('x'), point);
//=> 1
Try It Yourself

How It Works

R.lensProp('x') is the official pair in one argument. Keep R.lens when the getter or setter is not a simple property.

📈 Practical Patterns

A custom array-head lens, proof the source is unchanged, then a curried over in a pipeline.

Example 3 — Custom Array Head

nth(0) reads the first item. update(0) writes a new list.

Ramda
const headLens = R.lens(R.nth(0), R.update(0));
const items = ['a', 'b', 'c'];

R.view(headLens, items);
//=> 'a'
R.set(headLens, 'x', items);
//=> ['x', 'b', 'c']
items;
//=> ['a', 'b', 'c']
Try It Yourself

How It Works

This is the idea behind R.lensIndex(0). Use the next helper when the focus is just an index. Use R.lens when you need a custom pair.

Example 4 — The Source Stays Put

set returns a new object. The original still has x: 1.

Ramda
const xLens = R.lens(R.prop('x'), R.assoc('x'));
const point = {x: 1, y: 2};
const updated = R.set(xLens, 4, point);

updated;
//=> {x: 4, y: 2}
point;
//=> {x: 1, y: 2}
Try It Yourself

How It Works

assoc clones the top level. If you passed a setter that wrote obj.x = val, the original would change. The docs warn against that.

Example 5 — over with Curry

Bump x with inc, then read it. Both helpers are data-last.

Ramda
const xLens = R.lens(R.prop('x'), R.assoc('x'));
const bumpX = R.over(xLens, R.inc);
const readX = R.view(xLens);
const point = {x: 1, y: 2};

bumpX(point);
//=> {x: 2, y: 2}
readX(bumpX(point));
//=> 2
Try It Yourself

How It Works

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.

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 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.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.
const xLens = R.lens(R.prop('x'), R.assoc('x')). R.view(xLens, {x: 1, y: 2}) is 1. R.set(xLens, 4, {x: 1, y: 2}) is {x: 4, y: 2}. R.over(xLens, R.negate, {x: 1, y: 2}) is {x: -1, y: 2}.
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.

Continue to R.lensIndex()

Learn how to focus get and set on one array index using Ramda R.lensIndex().

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