How to Use the TypeScript Array splice() Method

The TypeScript array splice() method changes an array in place: arr.splice(start, deleteCount, ...items) removes deleteCount elements at start, inserts any items there, and returns the removed elements as a new array. Use toSpliced() when you need a copy instead:

const removed = stops.splice(1, 2);      // remove 2 items from index 1
stops.splice(1, 0, "Denton");             // insert without removing

My test bench was TypeScript 7.0.2 with Node v22.22.2, strict mode on, and the printed arrays are from real runs.

You’ll see remove, insert and replace with one method, how splice differs from slice and toSpliced, the readonly error, and two bugs that splice causes in real code.

Remove, insert and replace with splice()

One method does all three jobs, depending on the arguments. Here a road-trip route gets edited step by step:

const stops: string[] = ["Austin", "Waco", "Dallas", "Tulsa", "Wichita"];

const removed = stops.splice(1, 2);                  // start 1, delete 2
console.log("removed:", removed, "| now:", stops);

stops.splice(1, 0, "Denton", "Norman");              // delete 0 -> insert
console.log("insert: ", stops);

const replaced = stops.splice(3, 1, "Oklahoma City"); // replace 1 item
console.log("replace:", stops, "| took out:", replaced);

const tail = stops.splice(-2);                        // negative start, no count
console.log("last 2: ", tail, "| left:", stops);

Output:

removed: [ 'Waco', 'Dallas' ] | now: [ 'Austin', 'Tulsa', 'Wichita' ]
insert:  [ 'Austin', 'Denton', 'Norman', 'Tulsa', 'Wichita' ]
replace: [ 'Austin', 'Denton', 'Norman', 'Oklahoma City', 'Wichita' ] | took out: [ 'Tulsa' ]
last 2:  [ 'Oklahoma City', 'Wichita' ] | left: [ 'Austin', 'Denton', 'Norman' ]

A negative start counts from the end, and leaving out the count removes everything from start onward. If you only need to add items at the ends, adding elements to an array in TypeScript covers push and unshift.

What is the difference between splice, slice and toSpliced?

They sound alike but behave very differently. slice() copies part of an array, toSpliced() returns a changed copy, and splice() edits the original:

const prices: number[] = [19.99, 5.25, 102.0, 7.5];

const copyPart = prices.slice(1, 3);              // copy of index 1..2, original untouched
console.log("slice:     ", copyPart, prices);

const newList = prices.toSpliced(1, 1, 6.75);     // ES2023: new array with the change
console.log("toSpliced: ", newList, prices);

const cut = prices.splice(1, 2);                  // mutates prices
console.log("splice:    ", cut, prices);

Output:

slice:      [ 5.25, 102 ] [ 19.99, 5.25, 102, 7.5 ]
toSpliced:  [ 19.99, 6.75, 102, 7.5 ] [ 19.99, 5.25, 102, 7.5 ]
splice:     [ 5.25, 102 ] [ 19.99, 7.5 ]

toSpliced() needs --target es2023 or later. I use it in React state updates, where mutating is a bug. Cutting an array into pieces is covered in splitting an array in TypeScript.

Fix the splice error on a readonly array

A readonly string[] has no mutating methods, so splice won’t compile:

const HOLIDAYS: readonly string[] = ["2026-11-26", "2026-12-25", "2027-01-01"];

HOLIDAYS.splice(0, 1);

Output:

splice_readonly.ts(3,10): error TS2551: Property 'splice' does not exist on type 'readonly string[]'. Did you mean 'slice'?

Switch to HOLIDAYS.toSpliced(0, 1), which is allowed because it doesn’t change the original. More on this type in readonly arrays in TypeScript.

Why does splice skip items inside a for loop?

Removing an element shifts every later element down one index. A forward loop then moves past the item that slid into the gap:

const orders = [
  { id: 1, status: "cancelled" },
  { id: 2, status: "cancelled" },
  { id: 3, status: "shipped" },
  { id: 4, status: "cancelled" },
];

const forward = structuredClone(orders);
for (let i = 0; i < forward.length; i++) {
  if (forward[i].status === "cancelled") forward.splice(i, 1);   // bug: skips the next item
}
console.log("forward loop: ", forward.map((o) => o.id));

const backward = structuredClone(orders);
for (let i = backward.length - 1; i >= 0; i--) {
  if (backward[i].status === "cancelled") backward.splice(i, 1);
}
console.log("backward loop:", backward.map((o) => o.id));

console.log("filter:       ", orders.filter((o) => o.status !== "cancelled").map((o) => o.id));

Output:

forward loop:  [ 2, 3 ]
backward loop: [ 3 ]
filter:        [ 3 ]

Loop backward when you must mutate, or use filter() to build a new array. Filtering by several fields is shown in filtering an array of objects in TypeScript.

Remove an item by value with indexOf and splice

splice needs an index, so pair it with indexOf(). Always check for -1 first:

function removeValue<T>(items: T[], value: T): boolean {
  const i = items.indexOf(value);
  if (i === -1) return false;          // splice(-1, 1) would delete the LAST item
  items.splice(i, 1);
  return true;
}

const cart = ["Mug", "Beans", "Filters"];
console.log(removeValue(cart, "Beans"), cart);
console.log(removeValue(cart, "Kettle"), cart);

const oops = ["Mug", "Filters"];
oops.splice(oops.indexOf("Kettle"), 1);
console.log("without the check:", oops);

Output:

true [ 'Mug', 'Filters' ]
false [ 'Mug', 'Filters' ]
without the check: [ 'Mug' ]

Without the check, a missing value deletes the last item instead, because -1 means “last” to splice. For every other removal pattern, see removing an item from an array in TypeScript.

splice() arguments and return values

Call	Effect	Returns
a.splice(i, n)	Removes n items at i	Removed items
a.splice(i, 0, x, y)	Inserts x, y at i	[]
a.splice(i, 1, x)	Replaces one item	The old item in an array
a.splice(-2)	Removes the last two	Those two
a.toSpliced(i, n, ...)	Nothing (copy)	The new array

For more array editing in TypeScript, try these:

• Remove duplicates from an array in TypeScript
• Clear an array while keeping its type
• Update an object in an array in TypeScript
• Concatenate arrays with concat()

Frequently asked questions