---
hide_title: false
hide_table_of_contents: false
pagination_next: null
pagination_prev: null
---
# Array.prototype.sort()

The **`sort()`** method sorts the elements of an array _[in place](https://en.wikipedia.org/wiki/In-place_algorithm)_ and returns the reference to the same array, now sorted. The default sort order is ascending, built upon converting the elements into strings, then comparing their sequences of UTF-16 code units values.

The time and space complexity of the sort cannot be guaranteed as it depends on the
implementation.

## Syntax

```js
// Functionless
sort()

// Arrow function
sort((a, b) => { /* … */ } )

// Compare function
sort(compareFn)

// Inline compare function
sort(function compareFn(a, b) { /* … */ })
```

### Parameters

- `compareFn` _**optional**_

  - : Specifies a function that defines the sort order. If omitted, the array elements are converted to strings, then sorted according to each character's Unicode code point value.

    - `a`
      - : The first element for comparison.
    - `b`
      - : The second element for comparison.

### Return value

The reference to the original array, now sorted. Note that the array is sorted _[in place](https://en.wikipedia.org/wiki/In-place_algorithm)_, and no copy is made.

## Description

If `compareFn` is not supplied, all non-`undefined` array
elements are sorted by converting them to strings and comparing strings in UTF-16 code
units order. For example, "banana" comes before "cherry". In a numeric sort, 9 comes
before 80, but because numbers are converted to strings, "80" comes before "9" in the
Unicode order. All `undefined` elements are sorted to the end of the array.

The `sort()` method preserves empty slots. If the source array is sparse, the empty slots are moved to the end of the array, and always come after all the `undefined`.

> **Note:** In UTF-16, Unicode characters above `\uFFFF` are
> encoded as two surrogate code units, of the range
> `\uD800` - `\uDFFF`. The value of each code unit is taken
> separately into account for the comparison. Thus the character formed by the surrogate
> pair `\uD855\uDE51` will be sorted before the character
> `\uFF3A`.

If `compareFn` is supplied, all non-`undefined` array
elements are sorted according to the return value of the compare function (all
`undefined` elements are sorted to the end of the array, with no call to
`compareFn`).

| `compareFn(a, b)` return value | sort order                         |
| ------------------------------ | ---------------------------------- |
| > 0                            | sort `a` after `b`                 |
| < 0                            | sort `a` before `b`                |
| === 0                          | keep original order of `a` and `b` |

So, the compare function has the following form:

```js
function compareFn(a, b) {
  if (a is less than b by some ordering criterion) {
    return -1;
  }
  if (a is greater than b by the ordering criterion) {
    return 1;
  }
  // a must be equal to b
  return 0;
}
```

More formally, the comparator is expected to have the following properties, in order to ensure proper sort behavior:

- _Pure_: The comparator does not mutate the objects being compared or any external state. (This is important because there's no guarantee _when_ and _how_ the comparator will be called, so any particular call should not produce visible effects to the outside.)
- _Stable_: The comparator returns the same result with the same pair of input.
- _Reflexive_: `compareFn(a, a) === 0`.
- _Anti-symmetric_: `compareFn(a, b)` and `compareFn(b, a)` must both be `0` or have opposite signs.
- _Transitive_: If `compareFn(a, b)` and `compareFn(b, c)` are both positive, zero, or negative, then `compareFn(a, c)` has the same positivity as the previous two.

A comparator conforming to the constraints above will always be able to return all of `1`, `0`, and `-1`, or consistently return `0`. For example, if a comparator only returns `1` and `0`, or only returns `0` and `-1`, it will not be able to sort reliably because _anti-symmetry_ is broken. A comparator that always returns `0` will cause the array to not be changed at all, but is reliable nonetheless.

The default lexicographic comparator satisfies all constraints above.

To compare numbers instead of strings, the compare function can subtract `b`
from `a`. The following function will sort the array in ascending order (if
it doesn't contain `Infinity` and `NaN`):

```js
function compareNumbers(a, b) {
  return a - b;
}
```

The `sort()` method is generic. It only expects the `this` value to have a `length` property and integer-keyed properties. Although strings are also array-like, this method is not suitable to be applied on them, as strings are immutable.
