toggle()

toggle<T>(array, element): T[]

Toggles the presence of an element in an array.

note

Uses strict equality (===). Only the first occurrence is removed.

---

Type Parameters

T: T

The type of elements in the array.

---

Parameters

array: readonly T[]

The source array.

element: T

The element to toggle.

---

Returns: T[]

A new array with the element added or removed.

---

Since

2.0.0

---

Performance

O(n) time & space, uses indexOf and filter/spread operations.

---

Also known as

symmetricDifference (Remeda, Ramda) · toggle (Radashi) · xor (Lodash) · ❌ (es-toolkit, Effect, Modern Dash, Antfu)

---

Example

toggle([1, 2, 3], 2);
// => [1, 3]

toggle([1, 2, 3], 4);
// => [1, 2, 3, 4]

---

How it works?

Toggle adds an element if absent, or removes it if present — a single operation for both actions. Uses reference equality (===) to find the element.

Toggle vs Filter vs Spread

Operation	Purpose	Result
toggle(arr, x)	Add or remove in one call	Toggles presence
arr.filter(i => i !== x)	Remove only	Always removes
[...arr, x]	Add only	Always appends (duplicates possible)

---

Use Cases

Manage selected items in a multi-select UI 📌

Toggle selection state for checkboxes, tags, or list items. Perfect for filter panels, shopping carts, or bulk action selectors.

#toggle#multi-select#checkbox#selection#filter

let selectedFilters = ["electronics", "in-stock"];

selectedFilters = toggle(selectedFilters, "on-sale");
// => ["electronics", "in-stock", "on-sale"]  (added)

selectedFilters = toggle(selectedFilters, "electronics");
// => ["in-stock", "on-sale"]  (removed)

Handle favorites or bookmarks 📌

Add or remove items from saved lists with a single action. Ideal for wishlists, reading lists, or starred content.

#favorites#bookmarks#wishlist#saved#toggle

let bookmarkedIds = [101, 205, 342];

bookmarkedIds = toggle(bookmarkedIds, 205);
// => [101, 342]  (removed)

bookmarkedIds = toggle(bookmarkedIds, 789);
// => [101, 342, 789]  (added)

Manage user permissions dynamically

Grant or revoke access rights with a single action. Useful for admin panels, role management, or feature flags.

#permissions#access control#grant#revoke#roles

let permissions = ["read", "write"];

permissions = toggle(permissions, "delete");
// => ["read", "write", "delete"]  (granted)

permissions = toggle(permissions, "write");
// => ["read", "delete"]  (revoked)