Skip to main content

groupBy()

groupBy<T, K>(array, iteratee): Partial<Record<K, T[]>>

Groups array elements by a key derived from each element.

note

Prefer native Object.groupBy() when targeting ES2024+.

Type Parameters​

T: T​

The type of elements in the array.

K: K extends PropertyKey​

The type of the grouping key.

Parameters​

array: readonly T[]​

The array to group.

iteratee: (value) => K​

A function that returns the grouping key for each element.

Returns: Partial<Record<K, T[]>>​

An object with keys mapping to arrays of elements.

See Also​

Object.groupBy()

Since​

2.0.0

Performance​

O(n) time & space.

Also known as​

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

Example​

const byAge = groupBy(
  [{ name: 'John', age: 25 }, { name: 'Jane', age: 30 }, { name: 'Bob', age: 25 }],
  (u) => u.age
);
// => { '25': [...], '30': [...] }

byAge[25];   // => [{ name: 'John', age: 25 }, { name: 'Bob', age: 25 }]
byAge['25']; // => same — object keys are coerced to strings at runtime

groupBy(['one', 'two', 'three'], (s) => s.length);
// => { '3': ['one', 'two'], '5': ['three'] }

How it works?​

Groups elements into arrays by a computed key. Unlike countBy which counts, groupBy collects the actual elements.

With iteratee function​

groupBy vs countBy​

FunctionReturnsUse case
groupBy{ key: T[] }Need the elements
countBy{ key: number }Only need counts

Use Cases​

Group users by role 📌​

Organize a list of users based on their role or permission. Perfect for admin dashboards, access management, or category-based displays.

const users = [
  { name: "Alice", role: "admin" },
  { name: "Bob", role: "user" },
  { name: "Charlie", role: "admin" },
  { name: "Diana", role: "guest" },
];

const usersByRole = groupBy(users, (u) => u.role);
// => {
//   admin: [{ name: "Alice", role: "admin" }, { name: "Charlie", role: "admin" }],
//   user: [{ name: "Bob", role: "user" }],
//   guest: [{ name: "Diana", role: "guest" }]
// }

Group products by category 📌​

Classify items or products by their category for organized display. Perfect for e-commerce, catalogs, or inventory systems.

const products = [
  { name: "iPhone", category: "electronics" },
  { name: "T-Shirt", category: "clothing" },
  { name: "MacBook", category: "electronics" },
  { name: "Jeans", category: "clothing" },
];

const productsByCategory = groupBy(products, (p) => p.category);
// => {
//   electronics: [{ name: "iPhone", ... }, { name: "MacBook", ... }],
//   clothing: [{ name: "T-Shirt", ... }, { name: "Jeans", ... }]
// }

Group events by date or period​

Organize events, logs, or transactions by day/month/year. Perfect for calendars, history logs, or time-based reports.

const events = [
  { title: "Meeting", date: "2025-12-19" },
  { title: "Lunch", date: "2025-12-19" },
  { title: "Conference", date: "2025-12-20" },
  { title: "Workshop", date: "2025-12-21" },
];

const eventsByDate = groupBy(events, (e) => e.date);
// => {
//   "2025-12-19": [{ title: "Meeting", ... }, { title: "Lunch", ... }],
//   "2025-12-20": [{ title: "Conference", ... }],
//   "2025-12-21": [{ title: "Workshop", ... }]
// }

Group patients by department or blood type​

Organize patient records by department for efficient hospital management. Essential for healthcare systems, triage optimization, and medical analytics.

const patients = [
  { id: "P001", name: "Jean Dupont", department: "cardiology", bloodType: "A+" },
  { id: "P002", name: "Marie Martin", department: "neurology", bloodType: "O-" },
  { id: "P003", name: "Pierre Bernard", department: "cardiology", bloodType: "B+" },
  { id: "P004", name: "Sophie Petit", department: "oncology", bloodType: "A+" },
  { id: "P005", name: "Luc Moreau", department: "neurology", bloodType: "AB+" },
];

// Group by department for ward management
const byDepartment = groupBy(patients, (p) => p.department);
// => {
//   cardiology: [P001, P003],
//   neurology: [P002, P005],
//   oncology: [P004]
// }

// Group by blood type for transfusion planning
const byBloodType = groupBy(patients, (p) => p.bloodType);
// => { "A+": [P001, P004], "O-": [P002], "B+": [P003], "AB+": [P005] }

Group logs by severity for monitoring dashboards​

Organize application logs by severity level for quick triage. Essential for monitoring dashboards, alerting systems, and incident response.

const logs = [
  { message: "User login successful", level: "info", timestamp: 1703001200 },
  { message: "Database connection timeout", level: "error", timestamp: 1703001250 },
  { message: "Deprecated API endpoint used", level: "warn", timestamp: 1703001300 },
  { message: "Cache miss for key user:42", level: "info", timestamp: 1703001350 },
  { message: "Unhandled promise rejection", level: "error", timestamp: 1703001400 },
];

const logsBySeverity = groupBy(logs, (log) => log.level);
// => {
//   info: [{ message: "User login successful", ... }, { message: "Cache miss...", ... }],
//   error: [{ message: "Database connection timeout", ... }, { message: "Unhandled...", ... }],
//   warn: [{ message: "Deprecated API endpoint used", ... }]
// }

// Quick error count for alerting
const errorCount = logsBySeverity.error?.length ?? 0;

Group orders by status for e-commerce pipelines​

Organize orders by fulfillment status for warehouse and logistics management. Critical for e-commerce platforms, order tracking, and operational dashboards.

const orders = [
  { id: "ORD-001", customer: "Alice", status: "shipped", total: 89.99 },
  { id: "ORD-002", customer: "Bob", status: "pending", total: 149.50 },
  { id: "ORD-003", customer: "Charlie", status: "delivered", total: 34.00 },
  { id: "ORD-004", customer: "Diana", status: "pending", total: 220.00 },
  { id: "ORD-005", customer: "Eve", status: "shipped", total: 75.00 },
];

const ordersByStatus = groupBy(orders, (o) => o.status);
// => {
//   shipped: [ORD-001, ORD-005],
//   pending: [ORD-002, ORD-004],
//   delivered: [ORD-003]
// }

// Calculate revenue pending fulfillment
const pendingRevenue = ordersByStatus.pending?.reduce((sum, o) => sum + o.total, 0) ?? 0;
// => 369.50