Ramda.js R.splitWhen() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
List

Definition

R.splitWhen(pred, list) cuts a list into two parts right before the first item that passes a test. Part 1 holds the items before that match; part 2 starts with the match (official Ramda docs). It cuts only once, never changes the original, and R.splitWhen(pred) is a reusable function for pipelines.

Stable since v0.19.0: R.splitWhen is not deprecated, experimental, or non-standard. JavaScript has no native version; the closest is findIndex() followed by two slice() calls.

Syntax

Call R.splitWhen. Start with this line.

Ramda
R.splitWhen(pred, list) or R.splitWhen(pred)(list)
CallWhat it does
R.splitWhen(pred, list) or R.splitWhen(pred)(list)Primary signature.
R.splitWhen(...)Call the list helper.

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

Library declarations
Ramda
R.splitWhen(pred, list) or R.splitWhen(pred)(list)

Parameters

ParameterDescription
predRequired. Function. Called with one item; a truthy result marks the cut
listOptional. Array. The list to cut; omit it to get a reusable function

Return Value

Return ValueDescription
*A pair: [before, fromMatch]

Ramda Examples

Example 1 — Split at the First 2 (Official Sample)

Cut once, right before the first item equal to 2.

Ramda
const list = [1, 2, 3, 1, 2, 3];

console.log(R.splitWhen(R.equals(2), list)); // [[1], [2, 3, 1, 2, 3]]
console.log(list);                           // [1, 2, 3, 1, 2, 3]
Try It Yourself

How It Works

  1. The test. R.equals(2) returns true only for the value 2.
  2. Collect misses. 1 fails the test, so it goes into part 1.
  3. First hit. The 2 at index 1 passes, so the cut happens just before it.
  4. One cut only. The second 2 stays in part 2, and list is unchanged.

Example 2 — First Passing Score vs R.partition

Same test, two helpers: one cuts once, the other groups every item.

Ramda
const scores = [12, 35, 50, 72, 40];
const passed = (n) => n >= 50;

console.log(R.splitWhen(passed, scores)); // [[12, 35], [50, 72, 40]]
console.log(R.partition(passed, scores)); // [[50, 72], [12, 35, 40]]
Try It Yourself

How It Works

  1. Find the first pass. 12 and 35 fail; 50 is the first score that passes.
  2. Cut there. splitWhen keeps order, so 40 stays in part 2 even though it fails.
  3. Group instead. R.partition tests every item: passes first, fails second.
  4. Pick by intent. “Where does it change?” → splitWhen. “Which ones pass?” → partition.

Example 3 — Separate a Header from the Body

A message header ends at the first blank line.

Ramda
const lines = ['From: Ana', 'Subject: Hi', '', 'Hello!', 'Bye.'];

const [head, body] = R.splitWhen(R.equals(''), lines);

console.log(head);         // ['From: Ana', 'Subject: Hi']
console.log(body);         // ['', 'Hello!', 'Bye.']
console.log(R.tail(body)); // ['Hello!', 'Bye.']
Try It Yourself

How It Works

  1. Test for a blank line. R.equals('') matches the empty string at index 2.
  2. Destructure. const [head, body] names both parts in one line.
  3. Blank line goes right. The match starts part 2, so body begins with ''.
  4. Drop it. R.tail removes the first item, leaving just the body text.

Example 4 — Logs Before and After the First Error

Split a list of objects at the first entry whose level is 'error'.

Ramda
const logs = [
  { level: 'info',  msg: 'start' },
  { level: 'info',  msg: 'load' },
  { level: 'error', msg: 'crash' },
  { level: 'info',  msg: 'retry' }
];

const isError = R.propEq('error', 'level');
const [before, fromError] = R.splitWhen(isError, logs);

console.log(R.pluck('msg', before));    // ['start', 'load']
console.log(R.pluck('msg', fromError)); // ['crash', 'retry']
Try It Yourself

How It Works

  1. Build the test. R.propEq('error', 'level') checks obj.level === 'error' (value first, then key).
  2. Cut at the first error. The two info entries before it go into before.
  3. Keep what follows. fromError starts with the crash and includes the later retry.
  4. Show messages. R.pluck('msg') pulls one field from each object.

Example 5 — Same as takeWhile + dropWhile

Split at the first negative number, then build each part separately.

Ramda
const isNeg = (n) => n < 0;
const notNeg = R.complement(isNeg);
const nums = [3, 5, -1, 4, -2];

console.log(R.splitWhen(isNeg, nums));  // [[3, 5], [-1, 4, -2]]
console.log(R.takeWhile(notNeg, nums)); // [3, 5]
console.log(R.dropWhile(notNeg, nums)); // [-1, 4, -2]
Try It Yourself

How It Works

  1. Flip the test. R.complement(isNeg) returns true for numbers that are not negative.
  2. Part 1. R.takeWhile(notNeg) keeps items until the first negative: [3, 5].
  3. Part 2. R.dropWhile(notNeg) skips those same items: [-1, 4, -2].
  4. One call instead of two. R.splitWhen(isNeg) returns both parts at once.

Browser & Runtime Support

R.splitWhen() is plain JavaScript inside Ramda 0.19.0+. It is a simple while loop plus Array.prototype.slice, which every JavaScript engine has had since ES3, so support depends only on loading Ramda.

✓ Ramda 0.19.0+ · Any JS runtime

Ramda.js R.splitWhen()

The UMD build (ramda.min.js) uses ES5 syntax, so it runs in every modern browser. Via npm it works in Node.js, Deno, and Bun with require or import.

100% With Ramda loaded
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer End of life · ES5 build may load, untested
Legacy only
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Node.js Supported · npm install ramda
Supported
Deno Supported · npm:ramda
Supported
Bun Supported · bun add ramda
Supported
R.splitWhen() Universal

Bottom line: Safe in any project that loads Ramda 0.19.0 or later. Use ramda.min.js from a CDN in the browser, or npm install ramda for Node, Deno, and Bun. The Try-it labs load [email protected] and use modern syntax (const, arrow functions, destructuring).

Frequently Asked Questions

A two-item array. The first part holds every item before the first match; the second part starts with the first match and holds everything after it. R.splitWhen(R.equals(2), [1, 2, 3, 1, 2, 3]) returns [[1], [2, 3, 1, 2, 3]].
The second part. None of the items in the first part pass the test, and the first item of the second part (if any) is the first match. Use R.tail on the second part if you want to drop the match.
No, it cuts only once, at the first match. Later matches stay in the second part. To cut at every match use R.splitWhenever; to group all matches together use R.partition.
No match gives [list, []] — everything lands in part 1. If the first item matches you get [[], list]. An empty list gives [[], []]. It never throws for these cases.
R.splitAt cuts at a position you already know. R.splitWhen finds the position for you with a test function. R.splitWhen(pred, list) gives the same result as R.splitAt(R.findIndex(pred, list), list) whenever a match exists.
No. R.splitWhen has been a stable Ramda List function since v0.19.0. It is not deprecated, experimental, or non-standard.

Next: R.splitWhenever()

Cut a list at every item that passes a test.

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