Suggest an edit

Improve this article

Refine the answer for “The toSorted() method”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

**`toSorted()` is the new, non-mutating counterpart of the `sort()` method in JavaScript, added in ECMAScript 2023 (ES14).** It lets you sort an array without changing the original one, returning a new sorted copy instead.

## Theory

### TL;DR
- `toSorted()` returns a **new** sorted array and leaves the original unchanged.
- `sort()`, on the contrary, sorts in place and returns a reference to that same array.
- The method accepts the same optional compare function as `sort()`.
- It appeared in ECMAScript 2023 together with `toReversed()`, `toSpliced()` and `with()`.
- Without `compareFn` the elements are compared as strings, so numbers need a comparator.
- Its main use is side-effect-free code: React, Redux, functional style.

### Quick example
```javascript
const numbers = [3, 1, 4, 2];
const sorted = numbers.toSorted((a, b) => a - b);

console.log(sorted);  // [1, 2, 3, 4]
console.log(numbers); // [3, 1, 4, 2], the original array is unchanged
```

Unlike `sort()`, which changes the original, `toSorted()` returns a new array with the sorted elements.

### Syntax and parameters
```javascript
const newArray = array.toSorted(compareFn);
```

| Parameter | Description |
| --- | --- |
| `compareFn` | (optional) a compare function, the same as for `sort()`, for example `(a, b) => a - b` |

### Comparison with sort()

| Method | Does it change the original array | What it returns | Is it safe |
| --- | --- | --- | --- |
| `sort()` | Yes | The same array | No |
| `toSorted()` | No | A new array | Yes |

An example that shows the difference:

```javascript
const arr = [5, 2, 9];

const sorted1 = arr.sort();      // mutates
const sorted2 = arr.toSorted();  // does not mutate

console.log(arr);     // [2, 5, 9], mutated
console.log(sorted1); // [2, 5, 9]
console.log(sorted2); // [2, 5, 9], a new independent array
```

### Sorting numbers and a custom comparator
```javascript
const nums = [10, 2, 5, 1];
const asc = nums.toSorted((a, b) => a - b);
const desc = nums.toSorted((a, b) => b - a);

console.log(asc);  // [1, 2, 5, 10]
console.log(desc); // [10, 5, 2, 1]
console.log(nums); // [10, 2, 5, 1], unchanged
```

The same source array can be sorted several different ways in a row, because no call spoils it.

### When to use it
- When keeping the **original data intact** matters, for example in React, Redux or functional code.
- When you need to sort data safely, with no side effects.
- When the array comes from props, state or a cache and must not be mutated.
- When one data set has to be displayed in several different sort orders.

### Related non-mutating methods (ES2023 and later)

| New method | Old counterpart | What it does | Does it mutate |
| --- | --- | --- | --- |
| `toReversed()` | `reverse()` | Reverses the order | No |
| `toSorted()` | `sort()` | Sorts | No |
| `toSpliced()` | `splice()` | Removes or inserts elements | No |
| `with()` | `arr[index] = value` | Replaces an element by index | No |

The method itself in brief:

| Question | Answer |
| --- | --- |
| What it does | Creates a sorted copy of the array |
| Does it change the original array | No |
| What it returns | A new array |
| Does it support a compare function | Yes |
| Example | `[3, 1, 2].toSorted((a, b) => a - b)` gives `[1, 2, 3]` |

In short: `toSorted()` is the safe, non-mutating alternative to `sort()` that returns a new sorted array and leaves the original untouched.

### Common mistakes
- Calling `toSorted()` without a comparator for numbers. Then the elements are compared as strings, and `[10, 2, 5, 1]` turns into `[1, 10, 2, 5]`.
- Confusing it with `sort()` and accidentally mutating shared data. It is `sort()` that mutates.
- Not storing the result: `arr.toSorted()` on its own changes nothing, because the original stays as it was.
- Treating the copy as deep. The copy is shallow: object elements in the new array are the very same references.
- Counting on the method in an old environment. It is ECMAScript 2023, so old browsers and Node.js versions need a polyfill or `[...arr].sort(...)`.
- Sorting React state with `sort()` and wondering why the component does not re-render: the array reference stayed the same.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts742 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.