Skip to main content

union()

union<T>(arrays): T[]

Creates an array of unique values from all given arrays using SameValueZero for equality.

note

First occurrence wins when duplicates are found.

Type Parameters​

T: T​

The type of elements in the arrays.

Parameters​

arrays: readonly (readonly T[])[]​

The arrays to combine.

Returns: T[]​

A new array with unique elements.

Since​

2.0.0

Performance​

O(n) — uses Set for constant-time lookups.

Also known as​

union (Lodash, es-toolkit, Remeda, Ramda, Effect) · unique (Radashi) · ❌ (Modern Dash, Antfu)

Example​

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

union([['a', 'b'], ['b', 'c']]);
// => ['a', 'b', 'c']

How it works?​

Combines multiple arrays into one with unique values. First occurrence wins — preserves order of first appearance.

Use Cases​

Combine arrays without duplicates 📌​

Merge multiple arrays into one with unique values. Perfect for merging lists, combining selections, or deduplicating data.

const team1 = ["Alice", "Bob", "Charlie"];
const team2 = ["Bob", "Diana", "Eve"];
const team3 = ["Alice", "Frank"];

const allMembers = union(team1, team2, team3);
// => ["Alice", "Bob", "Charlie", "Diana", "Eve", "Frank"]

Merge tag lists​

Combine tags from multiple sources into a unique set. Useful for content aggregation or search indexing.

const userTags = ["javascript", "react"];
const articleTags = ["react", "typescript", "nodejs"];
const projectTags = ["typescript", "testing"];

const allTags = union(userTags, articleTags, projectTags);
// => ["javascript", "react", "typescript", "nodejs", "testing"]

Aggregate permissions​

Combine permissions from multiple roles. Essential for access control systems.

const adminPerms = ["read", "write", "delete"];
const editorPerms = ["read", "write", "publish"];

const combinedPerms = union(adminPerms, editorPerms);
// => ["read", "write", "delete", "publish"]

Implement "Select All" in a selection model​

Merge all items from a category into the current selection without duplicates. Essential for "Select All" checkboxes in data tables and list components.

const currentSelection = ["item-1", "item-3"];
const categoryItems = ["item-1", "item-2", "item-3", "item-4", "item-5"];

// Select All: merge category into selection
const allSelected = union(currentSelection, categoryItems);
// => ["item-1", "item-3", "item-2", "item-4", "item-5"]

renderCheckboxes(categoryItems, allSelected);

Combine overlay scroll strategies​

Merge scroll event sources from multiple scrollable ancestors for an overlay. Perfect for overlay positioning that needs to track all scrollable containers.

const getScrollParents = (element: HTMLElement): string[] => {
  // Walk up the DOM to find scrollable ancestors
  const parents: string[] = [];
  let current = element.parentElement;
  while (current) {
    if (current.scrollHeight > current.clientHeight) {
      parents.push(current.id || current.tagName);
    }
    current = current.parentElement;
  }
  return parents;
};

const triggerScrollParents = getScrollParents(triggerElement);
const overlayScrollParents = getScrollParents(overlayElement);

// Track all unique scrollable ancestors
const allScrollSources = union(triggerScrollParents, overlayScrollParents);
allScrollSources.forEach((id) => {
  document.getElementById(id)?.addEventListener("scroll", repositionOverlay);
});

Merge visible columns from multiple saved views​

Combine column selections from different saved table views. Perfect for data tables with customizable column visibility.

const defaultColumns = ["name", "email", "status"];
const userColumns = ["name", "phone", "lastLogin"];
const adminColumns = ["name", "email", "role", "createdAt"];

const allVisibleColumns = union(defaultColumns, userColumns, adminColumns);
// => ["name", "email", "status", "phone", "lastLogin", "role", "createdAt"]