Returns an array containing the items from the specified collection, ordered by a comparator function based on the values computed using the expression predicate.

For example, [{id: 'foo'}, {id: 'bar'}] | orderBy:'id' would result in [{id: 'bar'}, {id: 'foo'}].

The collection can be an Array or array-like object (e.g. NodeList, jQuery object, TypedArray, String, etc).

The expression can be a single predicate, or a list of predicates each serving as a tie-breaker for the preceding one. The expression is evaluated against each item and the output is used for comparing with other items.

You can change the sorting order by setting reverse to true. By default, items are sorted in ascending order.

The comparison is done using the comparator function. If none is specified, a default, built-in comparator is used (see below for details - in a nutshell, it compares numbers numerically and strings alphabetically).

Under the hood

Ordering the specified collection happens in two phases:

1. All items are passed through the predicate (or predicates), and the returned values are saved along with their type (string, number etc). For example, an item {label: 'foo'}, passed through a predicate that extracts the value of the label property, would be transformed to:

   {
     value: 'foo',
     type: 'string',
     index: ...
   }
   

2. The comparator function is used to sort the items, based on the derived values, types and indices.

If you use a custom comparator, it will be called with pairs of objects of the form {value: ..., type: '...', index: ...} and is expected to return 0 if the objects are equal (as far as the comparator is concerned), -1 if the 1st one should be ranked higher than the second, or 1 otherwise.

In order to ensure that the sorting will be deterministic across platforms, if none of the specified predicates can distinguish between two items, orderBy will automatically introduce a dummy predicate that returns the item's index as value. (If you are using a custom comparator, make sure it can handle this predicate as well.)

Finally, in an attempt to simplify things, if a predicate returns an object as the extracted value for an item, orderBy will try to convert that object to a primitive value, before passing it to the comparator. The following rules govern the conversion:

1. If the object has a valueOf() method that returns a primitive, its return value will be used instead.
   (If the object has a valueOf() method that returns another object, then the returned object will be used in subsequent steps.)
2. If the object has a custom toString() method (i.e. not the one inherited from Object) that returns a primitive, its return value will be used instead.
   (If the object has a toString() method that returns another object, then the returned object will be used in subsequent steps.)
3. No conversion; the object itself is used.

The default comparator

The default, built-in comparator should be sufficient for most usecases. In short, it compares numbers numerically, strings alphabetically (and case-insensitively), for objects falls back to using their index in the original collection, and sorts values of different types by type.

More specifically, it follows these steps to determine the relative order of items:

1. If the compared values are of different types, compare the types themselves alphabetically.
2. If both values are of type string, compare them alphabetically in a case- and locale-insensitive way.
3. If both values are objects, compare their indices instead.
4. Otherwise, return:
   • 0, if the values are equal (by strict equality comparison, i.e. using ===).
   • -1, if the 1st value is "less than" the 2nd value (compared using the < operator).
   • 1, otherwise.

Note: If you notice numbers not being sorted as expected, make sure they are actually being saved as numbers and not strings. Note: For the purpose of sorting, null values are treated as the string 'null' (i.e. type: 'string', value: 'null'). This may cause unexpected sort order relative to other values.