Ramda.js R.when() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Logic

Definition

Ramda’s R.when() answers a guarded-transform question: should this value take the transformer or pass through unchanged? You pass a predicate and a function. You get back one function. Call that leftover with a value. Native JavaScript might write pred(x) ? whenTrueFn(x) : x. when names that guard once, curries it, and only runs the transformer on a pass. Drop the leftover into R.map and R.pipe.

The official sample is the whole idea. Truncate only when the string length exceeds 10. Short strings pass through. Need a transform only when the test fails? That is R.unless. Need both branches to always transform? That is R.ifElse. Need more than two branches? That is R.cond. Previous Logic helper is R.until for iterative loops. Next is R.xor for exclusive OR of two values.

Syntax

Call R.when. Start with this line.

Ramda
R.when(pred, whenTrueFn, x)
CallWhat it does
R.when(pred, whenTrueFn, x)Primary signature.
R.when(...)Call the logic helper.

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

Library declarations
Ramda
R.when(pred, whenTrueFn, x)

Parameters

ParameterDescription
predRequired. Function. A predicate. Called with the same arguments you later pass to the leftover. Truthy result calls whenTrueFn.
whenTrueFnRequired. Function. Runs only when the predicate is truthy. Accepts Ramda's placeholder R.__.
xRequired. Any. The value to test. On a pass you get the transformer result. On a miss you get this value back.

Return Value

Return ValueDescription
a | bEither the original x on a miss, or whatever whenTrueFn returns on a pass.

Ramda Examples

📚 Getting Started

The official Ramda truncate sample, then the same idea compared with unless, ifElse, and cond.

Example 1 — Official Truncate

Truncate only when the string length exceeds 10. Short strings pass through unchanged.

Ramda
const truncate = R.when(
  R.propSatisfies(R.gt(R.__, 10), 'length'),
  R.pipe(R.take(10), R.append('…'), R.join(''))
);

truncate('12345');
//=> '12345'

truncate('0123456789ABC');
//=> '0123456789…'
Try It Yourself

How It Works

R.propSatisfies(R.gt(R.__, 10), 'length') is the predicate. Short strings fail, so they pass through. Long strings pass, so the pipe takes 10 chars, appends an ellipsis, and joins. That is the docs sample from ramdajs.com.

Example 2 — vs unless, ifElse, and cond

when is the inverse of unless. ifElse always picks a branch. cond is the list form.

Ramda
R.when(R.equals(0), R.always('freeze'))(0);
//=> 'freeze'

R.unless(R.equals(0), R.inc)(0);
//=> 0

R.ifElse(R.equals(0), R.always('freeze'), R.always('other'))(0);
//=> 'freeze'

R.cond([
  [R.equals(0), R.always('freeze')],
  [R.T, R.always('other')]
])(0);
//=> 'freeze'
Try It Yourself

How It Works

when transforms 0 because it equals 0 — the predicate passes, so R.always('freeze') runs. unless keeps 0 unchanged because the predicate passes. R.cond is the same fork as a list of pairs.

📈 Practical Patterns

Pass runs the transformer, fail keeps the original, then map strings and pipe vs ternary.

Example 3 — Predicate Pass Runs Fn / Fail Keeps Original

When the predicate passes, whenTrueFn runs. When it fails, x is returned unchanged.

Ramda
const gtZero = R.gt(R.__, 0);

R.when(gtZero, R.inc)(5);
//=> 6

R.when(gtZero, R.inc)(-3);
//=> -3

R.when(R.isEmpty, R.always('(empty)'))('');
//=> '(empty)'

R.when(R.isEmpty, R.always('(empty)'))('hi');
//=> 'hi'
Try It Yourself

How It Works

5 is greater than 0, so the predicate passes and R.inc runs. -3 fails, so -3 comes back unchanged. Empty strings pass R.isEmpty, so the placeholder runs. Non-empty strings fail and pass through.

Example 4 — Map Strings with Empty Label

Non-empty strings stay unchanged. Empty strings become '(empty)'.

Ramda
const strings = ['hello', '', 'world', ''];

const labelEmpty = R.when(R.isEmpty, R.always('(empty)'));

R.map(labelEmpty, strings);
//=> ['hello', '(empty)', 'world', '(empty)']
Try It Yourself

How It Works

R.isEmpty passes for '', so R.always('(empty)') runs. Non-empty strings fail the predicate and pass through. One leftover maps over the whole list.

Example 5 — Pipe Step vs Manual Ternary

The when leftover slots into R.pipe the same way a hand-written length guard would.

Ramda
const truncate = R.when(
  R.propSatisfies(R.gt(R.__, 10), 'length'),
  R.pipe(R.take(10), R.append('…'), R.join(''))
);
const piped = R.pipe(truncate);
const manual = s => s.length > 10 ? s.slice(0, 10) + '…' : s;

piped('12345');
//=> '12345'

piped('0123456789ABC');
//=> '0123456789…'

manual('12345');
//=> '12345'

manual('0123456789ABC');
//=> '0123456789…'
Try It Yourself

How It Works

R.pipe(truncate) is the point-first style. The manual ternary does the same length guard inline. when names the pattern once so the pipe stays readable.

Browser Support

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

✓ Ramda 0.18.0+ · Any JS runtime

Ramda.js R.when()

Load Ramda 0.18.0 or later via CDN or npm, then call R.when with a predicate and transformer. No extra browser API is required.

100% With Ramda 0.18.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.when() Universal

Bottom line: Safe in any project that includes Ramda 0.18.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.when(pred, whenTrueFn, x) takes a predicate and a transformer. If pred(x) is truthy, whenTrueFn(x) runs. If pred(x) is falsy, x is returned unchanged. Added in v0.18.0. Type: (a → Boolean) → (a → b) → a → a | b. Arity 3, curried.
truncate = R.when(R.propSatisfies(R.gt(R.__, 10), 'length'), R.pipe(R.take(10), R.append('…'), R.join(''))). truncate('12345') is '12345'. truncate('0123456789ABC') is '0123456789…'. Short strings pass through. Long strings get truncated.
when transforms only on a pass and keeps the original on a miss. unless transforms only on a miss. ifElse always runs one of two transformers. cond is a list of [predicate, transformer] pairs for many branches.
No. On a pass you get whatever whenTrueFn returns: a number, object, string, or anything else. On a miss you get the original x back.
Yes. when transforms on a pass and otherwise returns x. unless transforms on a miss and otherwise returns x. Same predicate, opposite side of the fork.
No. R.when is a stable Ramda logic helper from v0.18.0. It is not deprecated, experimental, or non-standard.

Continue to R.xor()

Learn exclusive OR of two values with Ramda R.xor().

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