> 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.

# sortBy es-toolkit

Returns a new array sorted in ascending order by the given criteria.

```typescript
const sorted = sortBy(arr, criteria);
```

## Usage

### `sortBy(arr, criteria)`

Use `sortBy` when you want to sort an array of objects by multiple properties or computed values. Provide property names or transformation functions as an array, and it sorts in ascending order with priority in that order. It's useful for sorting table data or when complex sorting logic is needed.

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

// Sort by a single property.
const users = [
  { name: 'john', age: 30 },
  { name: 'jane', age: 25 },
  { name: 'bob', age: 35 },
];
const byAge = sortBy(users, ['age']);
// Returns: [{ name: 'jane', age: 25 }, { name: 'john', age: 30 }, { name: 'bob', age: 35 }]

// Sort by multiple properties.
const employees = [
  { name: 'john', department: 'engineering', age: 30 },
  { name: 'jane', department: 'hr', age: 25 },
  { name: 'bob', department: 'engineering', age: 35 },
  { name: 'alice', department: 'engineering', age: 25 },
];
const sorted = sortBy(employees, ['department', 'age']);
// Returns: Sort by department first, then by age
// [
//   { name: 'alice', department: 'engineering', age: 25 },
//   { name: 'john', department: 'engineering', age: 30 },
//   { name: 'bob', department: 'engineering', age: 35 },
//   { name: 'jane', department: 'hr', age: 25 }
// ]
```

You can create complex sorting criteria using functions.

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

// Mix functions and properties.
const products = [
  { name: 'laptop', price: 1000, category: 'electronics' },
  { name: 'shirt', price: 50, category: 'clothing' },
  { name: 'phone', price: 800, category: 'electronics' },
];

const sorted = sortBy(products, [
  'category',
  item => -item.price, // Sort price in descending order
]);
// Returns: Sort by category first, then by highest price

// Sort by computed values.
const words = ['hello', 'a', 'wonderful', 'world'];
const byLength = sortBy(
  words.map(word => ({ word, length: word.length })),
  ['length']
);
// Returns: Array of objects sorted by string length
```

#### Parameters


arrreadonly T[]required

The array of objects to sort.


criteriaReadonlyArray<((item: T) => unknown) | keyof T>required

Sorting criteria. An array of object property names or transformation functions, with earlier criteria having higher priority.

#### Returns

Returns a new array sorted in ascending order by the specified criteria.

```typescript
T[]
```


Source: es-toolkit

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