.toSorted()

Published Jul 12, 2023
Contribute to Docs

The .toSorted() method takes an array and returns a new array with the elements sorted in ascending order. It does not mutate the original array. All undefined elements are sorted to the end of the array.

The sorting is done by converting array elements to strings and comparing them by Unicode code point value.

Syntax

// Functionless

array.toSorted();

// Arrow function
// 'a' is the first element for comparison and 'b' is the second.

array.toSorted((a, b) => { /* Code for a compare function. */ });

// Compare function
// 'compareFn' specifies a function that defines the sort order.

function compareFn() {
  /* Code for a compare function. */
};

array.toSorted(compareFn);

//  Inline compare function

array.toSorted(function compareFn(a, b) { /* … */ });

Example

In the example below, the .toSorted() method is applied to the arrays sports and numbers.

const sports = [
'baseball',
'basketball',
'tennis',
'pickleball',
undefined,
'',
];
const numbers = [-3, 4, 1, 9, 3, 2, 1, 200, 2159.2, 959, undefined, ''];
let sportsSorted = sports.toSorted();
let numbersSorted = numbers.toSorted();
console.log('Sports: ' + sportsSorted);
console.log('Numbers: ' + numbersSorted);

Which outputs:

Sports: ,baseball,basketball,pickleball,tennis,
Numbers: ,-3,1,1,2,200,2159.2,3,4,9,959,

sports was sorted alphabetically but numbers was sorted by unicode value. Remember that toSorted() converts elements to strings and compares them using Unicode code point value.

Additionally, undefined values were sorted to the end and empty strings (Unicode value of 0) were sorted to the beginning for both arrays.

To sort by numerical values, we require a comparison function. The code below takes the numbers array and sorts it two ways - ascending then descending. It then saves the new arrays to two variables and logs those.

const numbers = [-3, 4, 1, 9, 3, 2, 1, 200, 959, 2159.2];
let ascending = numbers.toSorted(function compareFn(a, b) {
return a - b;
});
let descending = numbers.toSorted(function compareFn(a, b) {
return b - a;
});
console.log('Numbers Ascending: ' + ascending);
console.log('Numbers Descending: ' + descending);

Which outputs:

Numbers Ascending: -3,1,1,2,3,4,9,200,959,2159.2
Numbers Descending: 2159.2,959,200,9,4,3,2,1,1,-3

All contributors

Looking to contribute?

Learn JavaScript on Codecademy