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/groupBy.md.
Install massaman

    groupBy es-toolkit

    Returns a new object with array elements grouped according to a key-generating function.

    const grouped = groupBy(arr, getKeyFromItem);

    Usage

    groupBy(arr, getKeyFromItem)

    Use groupBy when you want to classify array elements based on specific criteria. Provide a function that generates a key from each element, and it groups elements with the same key together and returns them as an object. The values in the returned object are arrays of elements belonging to each group. This is useful for organizing data by category or performing group-based analysis.

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

// Group an array of objects by category
const items = [
  { category: 'fruit', name: 'apple' },
  { category: 'fruit', name: 'banana' },
  { category: 'vegetable', name: 'carrot' },
];

const result = groupBy(items, item => item.category);
// Result:
// {
//   fruit: [
//     { category: 'fruit', name: 'apple' },
//     { category: 'fruit', name: 'banana' }
//   ],
//   vegetable: [
//     { category: 'vegetable', name: 'carrot' }
//   ]
// }

    You can group by various criteria.

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

// Group by string length
const words = ['one', 'two', 'three', 'four', 'five'];
const byLength = groupBy(words, word => word.length);
// Result: { 3: ['one', 'two'], 4: ['four', 'five'], 5: ['three'] }

// Group by even/odd
const numbers = [1, 2, 3, 4, 5, 6];
const byParity = groupBy(numbers, num => (num % 2 === 0 ? 'even' : 'odd'));
// Result: { odd: [1, 3, 5], even: [2, 4, 6] }

    Parameters

    arrT[]required

    The array to group.

    getKeyFromItem(item: T, index: number, array: T[]) => Krequired

    A function that generates a key from each element, its index, and the array.

    Returns

    Returns an object with elements grouped by key.

    Record<K, T[]>

    Examples

    // Using index parameter
const items = ['a', 'b', 'c', 'd'];
const result = groupBy(items, (item, index) => (index % 2 === 0 ? 'even' : 'odd'));
// Result: { even: ['a', 'c'], odd: ['b', 'd'] }

// Using array parameter
const numbers = [1, 2, 3, 4];
const result2 = groupBy(numbers, (item, index, arr) => (item < arr.length / 2 ? 'small' : 'large'));
// Result: { small: [1], large: [2, 3, 4] }
    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.