Ramda.js R.insert() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
List

Definition

R.insert(index, item, list) returns a new list with item placed at index. Everything from that position moves one step right, and the original list is not changed (official Ramda docs).

Stable since v0.2.2: R.insert is not deprecated, experimental, or non-standard. Note: a negative index adds the item at the end, unlike native splice.

Syntax

Call R.insert. Start with this line.

Ramda
R.insert(index, item, list)
CallWhat it does
R.insert(index, item, list)Primary signature.
R.insert(...)Call the list helper.

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

Library declarations
Ramda
R.insert(index, item, list)

Parameters

ParameterDescription
indexRequired. Number. Where the new item goes (0 = start)
itemRequired. Any. The single item to add
listRequired. Array. The list to copy and insert into

Return Value

Return ValueDescription
*The value returned by R.insert().

Ramda Examples

Example 1 — Official Sample

Put 'x' at index 2, as in the Ramda docs.

Ramda
const result = R.insert(2, 'x', [1, 2, 3, 4]);

console.log(JSON.stringify(result)); // [1,2,"x",3,4]
Try It Yourself

How It Works

  1. Argument order. Index first, item second, list last.
  2. Position 2. The item at index 2 is 3, so 'x' goes just before it.
  3. Shift. 3 and 4 move one step right.
  4. Longer list. The result has 5 items; the input still has 4.

Example 2 — The Original List Stays the Same

Insert into a list, then print both the new list and the old one.

Ramda
const letters = ['a', 'c'];
const fixed = R.insert(1, 'b', letters);

console.log(JSON.stringify(fixed));   // ["a","b","c"]
console.log(JSON.stringify(letters)); // ["a","c"]
Try It Yourself

How It Works

  1. Copy first. Ramda copies letters before changing anything.
  2. Insert. 'b' goes at index 1 of the copy, giving fixed.
  3. Untouched. letters is still ['a', 'c'].
  4. Compare. Native letters.splice(1, 0, 'b') would change letters itself.

Example 3 — Start, End, and a Negative Index

Index 0 adds at the start. The length or any negative number adds at the end.

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

console.log(JSON.stringify(R.insert(0, 'x', xs)));  // ["x",1,2,3]
console.log(JSON.stringify(R.insert(3, 'x', xs)));  // [1,2,3,"x"]
console.log(JSON.stringify(R.insert(-1, 'x', xs))); // [1,2,3,"x"]
Try It Yourself

How It Works

  1. Index 0. Before the first item — same as R.prepend.
  2. Index 3. Equals the length, so it goes at the end — same as R.append.
  3. Index -1. Out of range, so Ramda also puts it at the end.
  4. Watch out. Native splice(-1, 0, 'x') would give [1, 2, 'x', 3] instead.

Example 4 — Insert into a Sorted List

Find the first bigger number, then insert before it. Keeps the list sorted.

Ramda
const insertSorted = (x, xs) =>
  R.insert(R.findIndex(n => n > x, xs), x, xs);

console.log(JSON.stringify(insertSorted(5, [1, 3, 7, 9])));  // [1,3,5,7,9]
console.log(JSON.stringify(insertSorted(10, [1, 3, 7, 9]))); // [1,3,7,9,10]
Try It Yourself

How It Works

  1. Find the spot. R.findIndex returns 2, the index of 7, the first number bigger than 5.
  2. Insert. 5 goes before 7.
  3. Nothing bigger. For 10, findIndex returns -1.
  4. Handy rule. R.insert treats -1 as “the end”, so 10 is appended with no extra check.

Example 5 — R.insert vs R.insertAll

Inserting an array is not the same as inserting its items.

Ramda
const extra = ['x', 'y'];

console.log(JSON.stringify(R.insert(1, extra, [1, 2])));    // [1,["x","y"],2]
console.log(JSON.stringify(R.insertAll(1, extra, [1, 2]))); // [1,"x","y",2]
Try It Yourself

How It Works

  1. insert. Treats extra as one item, so the array is nested inside.
  2. insertAll. R.insertAll spreads the items into the list.
  3. Lengths. The first result has 3 items, the second has 4.
  4. Rule of thumb. One item → insert; several → insertAll.

Browser & Runtime Support

R.insert() has been in Ramda since v0.2.2. It only uses slice and splice, which every JavaScript engine supports.

✓ Ramda 0.2.2+ · Any JS runtime

Ramda.js R.insert()

The UMD build (ramda.min.js) is compiled to ES5 syntax, so it runs in Chrome, Firefox, Safari, and Edge. 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 No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
R.insert() Universal

Bottom line: Safe in any project with Ramda. The native non-mutating alternative, Array.prototype.toSpliced, is newer (ES2023): Chrome 110+, Firefox 115+, Safari 16+, Node 20+. These labs load [email protected].

Frequently Asked Questions

R.insert(index, item, list) returns a new list with item placed at index. Items from that position onward move one step right. The original list is never changed.
No. Ramda copies the list first and inserts into the copy. Native array.splice changes the array in place; R.insert does not.
The item is added at the end. R.insert(-1, 'x', [1, 2, 3]) and R.insert(99, 'x', [1, 2, 3]) both give [1, 2, 3, 'x']. This differs from native splice, where -1 means before the last item.
Use R.insertAll(index, items, list). Passing an array to R.insert adds that array as a single nested item: R.insert(1, ['x', 'y'], [1, 2]) is [1, ['x', 'y'], 2].
array.toSpliced(index, 0, item) also returns a new array (ES2023: Chrome 110, Firefox 115, Safari 16, Node 20). It treats negative indexes as counting from the end, unlike R.insert.
No. R.insert has been a stable Ramda List function since v0.2.2. It is not deprecated, experimental, or non-standard.

Next: R.insertAll()

Add several items at a position in one step.

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