TheObject.groupBy() static method groups the elements of a given iterable according to the string values returned by a provided callback function. The returned object has separate properties for each group, containing arrays with the elements in the group.

This method should be used when group names can be represented by strings. If you need to group elements using a key that is some arbitrary value, useMap.groupBy() instead.

Try it

const inventory = [  { name: "asparagus", type: "vegetables", quantity: 9 },  { name: "bananas", type: "fruit", quantity: 5 },  { name: "goat", type: "meat", quantity: 23 },  { name: "cherries", type: "fruit", quantity: 12 },  { name: "fish", type: "meat", quantity: 22 },];const result = Object.groupBy(inventory, ({ quantity }) =>  quantity < 6 ? "restock" : "sufficient",);console.log(result.restock);// [{ name: "bananas", type: "fruit", quantity: 5 }]

Syntax

Object.groupBy(items, callbackFn)

Parameters

items

Aniterable (such as anArray) whose elements will be grouped.

callbackFn

A function to execute for each element in the iterable. It should return a value that can get coerced into a property key (string orsymbol) indicating the group of the current element. The function is called with the following arguments:

element

The current element being processed.

index

The index of the current element being processed.

Return value

Anull-prototype object with properties for all groups, each assigned to an array containing the elements of the associated group.

Description

Object.groupBy() calls a providedcallbackFn function once for each element in an iterable. The callback function should return a string or symbol (values that are neither type arecoerced to strings) indicating the group of the associated element. The values returned bycallbackFn are used as keys for the object returned byObject.groupBy(). Each key has an associated array containing all the elements for which the callback returned the same value.

The elements in the returned object and the original iterable are the same (notdeep copies). Changing the internal structure of the elements will be reflected in both the original iterable and the returned object.

Examples

Using Object.groupBy()

First we define an array containing objects representing an inventory of different foodstuffs. Each food has atype and aquantity.

const inventory = [  { name: "asparagus", type: "vegetables", quantity: 5 },  { name: "bananas", type: "fruit", quantity: 0 },  { name: "goat", type: "meat", quantity: 23 },  { name: "cherries", type: "fruit", quantity: 5 },  { name: "fish", type: "meat", quantity: 22 },];

The code below groups the elements by the value of theirtype property.

const result = Object.groupBy(inventory, ({ type }) => type);/* Result is:{  vegetables: [    { name: 'asparagus', type: 'vegetables', quantity: 5 },  ],  fruit: [    { name: "bananas", type: "fruit", quantity: 0 },    { name: "cherries", type: "fruit", quantity: 5 }  ],  meat: [    { name: "goat", type: "meat", quantity: 23 },    { name: "fish", type: "meat", quantity: 22 }  ]}*/

The arrow function just returns thetype of each array element each time it is called. Note that the function argument{ type } is a basic example ofobject destructuring syntax for function arguments. This unpacks thetype property of an object passed as a parameter, and assigns it to a variable namedtype in the body of the function.This is a very succinct way to access the relevant values of elements within a function.

We can also create groups inferred from values in one or more properties of the elements. Below is a very similar example that puts the items intook orrestock groups based on the value of thequantity field.

function myCallback({ quantity }) {  return quantity > 5 ? "ok" : "restock";}const result2 = Object.groupBy(inventory, myCallback);/* Result is:{  restock: [    { name: "asparagus", type: "vegetables", quantity: 5 },    { name: "bananas", type: "fruit", quantity: 0 },    { name: "cherries", type: "fruit", quantity: 5 }  ],  ok: [    { name: "goat", type: "meat", quantity: 23 },    { name: "fish", type: "meat", quantity: 22 }  ]}*/

Specifications

Browser compatibility

See also

• Polyfill ofObject.groupBy incore-js
• es-shims polyfill ofObject.groupBy
• Indexed collections guide
• Array.prototype.reduce()
• Object.fromEntries()
• Map.groupBy()