For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/array/unionBy.md.
Install massaman

    unionBy es-toolkit

    Creates a new array containing unique elements from two arrays based on values transformed by a specific function.

    const unified = unionBy(arr1, arr2, mapper);

    Usage

    unionBy(arr1, arr2, mapper)

    Use unionBy when you want to remove duplicates based on a specific property from object arrays. Elements are treated as identical if the values returned by the mapper function are the same.

    import { unionBy } from 'es-toolkit/array';

// Get the union of objects based on id.
const users1 = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
];
const users2 = [
  { id: 2, name: 'Bob' },
  { id: 3, name: 'Charlie' },
];
unionBy(users1, users2, user => user.id);
// Returns: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' }]

// Get the union based on the remainder when dividing by 3.
const nums1 = [1, 2, 3];
const nums2 = [4, 5, 6];
unionBy(nums1, nums2, x => x % 3);
// Returns: [1, 2, 3]
// 1 % 3 = 1, 2 % 3 = 2, 3 % 3 = 0,
// 4 % 3 = 1, 5 % 3 = 2, 6 % 3 = 0, so all are duplicates.

    You can also get unions by complex criteria using custom comparison functions.

    import { unionBy } from 'es-toolkit/array';

const products1 = [
  { category: 'electronics', price: 100 },
  { category: 'books', price: 20 },
];
const products2 = [
  { category: 'electronics', price: 150 },
  { category: 'toys', price: 30 },
];

// Get the union based on category.
unionBy(products1, products2, product => product.category);
// Returns: [
//   { category: 'electronics', price: 100 },
//   { category: 'books', price: 20 },
//   { category: 'toys', price: 30 }
// ]

    Parameters

    arr1T[]required

    The first array to merge.

    arr2T[]required

    The second array to merge.

    mapper(item: T) => Urequired

    A function that transforms each element into a value for comparison.

    Returns

    Returns the union of the two arrays with duplicates removed based on values returned by the mapper function.

    T[]
    Source: es-toolkit

    Re-exported verbatim from es-toolkit. Implementation, edge cases, and performance behavior are owned upstream. This page mirrors the documentation at the pinned version; the linked source is authoritative.