> For AI agents: the complete documentation index is available at https://massaman.dev/llms.txt, the full documentation bundle is available at https://massaman.dev/llms-full.txt.

# unionWith es-toolkit

Creates a new array containing unique elements from two arrays based on a custom equality function.

```typescript
const unified = unionWith(arr1, arr2, areItemsEqual);
```

## Usage

### `unionWith(arr1, arr2, areItemsEqual)`

Use `unionWith` when you want to determine element equality by complex conditions. If the provided function returns true, the two elements are considered the same and duplicates are removed.

```typescript
import { unionWith } from 'es-toolkit/array';

// Get the union based on object id.
const array1 = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
];
const array2 = [
  { id: 2, name: 'Bob' },
  { id: 3, name: 'Charlie' },
];
const areItemsEqual = (a, b) => a.id === b.id;
unionWith(array1, array2, areItemsEqual);
// Returns: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' }]
```

You can also use more complex comparison logic.

```typescript
import { unionWith } from 'es-toolkit/array';

// Get the union based on coordinates.
const points1 = [
  { x: 1, y: 2 },
  { x: 3, y: 4 },
];
const points2 = [
  { x: 3, y: 4 },
  { x: 5, y: 6 },
];
const arePointsEqual = (p1, p2) => p1.x === p2.x && p1.y === p2.y;
unionWith(points1, points2, arePointsEqual);
// Returns: [{ x: 1, y: 2 }, { x: 3, y: 4 }, { x: 5, y: 6 }]
```

Here's an example of case-insensitive string comparison.

```typescript
import { unionWith } from 'es-toolkit/array';

const words1 = ['Apple', 'banana'];
const words2 = ['BANANA', 'orange'];
const areWordsEqual = (a, b) => a.toLowerCase() === b.toLowerCase();
unionWith(words1, words2, areWordsEqual);
// Returns: ['Apple', 'banana', 'orange']
// 'banana' and 'BANANA' are considered the same, so only the first one is kept.
```

#### Parameters


arr1T[]required

The first array to merge.


arr2T[]required

The second array to merge.


areItemsEqual(item1: T, item2: T) => booleanrequired

A function that determines if two elements are equal. It should return `true` if they are considered equal, and `false` otherwise.

#### Returns

Returns the union of the two arrays with duplicates removed based on the custom equality function.

```typescript
T[]
```


Source: es-toolkit

Re-exported verbatim from [`es-toolkit`](https://es-toolkit.dev/reference/array/unionWith.html). Implementation, edge cases, and performance behavior are owned upstream. This page mirrors the documentation at the pinned version; the linked source is authoritative.
