A filter formats a value for display. For example, a filter can sort a list or convert an object to JSON. Filters do not replace methods that change application state.
This is the multi-page printable view of this section. Click here to print.
Filters
Transform displayed values in templates without changing the stored value.
- 1: Async
- 2: Filter collections
- 3: Collection filters
- 4: JSON
- 5: Date
- 6: Limit to
- 7: Number, currency, and percent
- 8: Order by
- 9: Relative time
1 - Async
Render a promise result when it settles.
The async filter returns undefined while a promise-like value is pending.
When it settles, AngularTS schedules change detection and returns the resolved
value. A rejection is exposed as the settled value so the view can decide how to
present it.
<p>{{ profilePromise | async }}</p>
Keep the same promise instance between render passes. Creating a promise in the template starts new work repeatedly; create it in a controller or model instead.
2 - Filter collections
Select collection items with a string, object, or predicate.
/**
- @ngdoc filter
- @name filter
- @kind function
- @description
- Selects a subset of items from
arrayand returns it as a new array. - @param {Array} array The source array.
- Note: If the array contains objects that reference themselves, filtering is not possible.
- @param {string|Object|function()} expression The predicate to be used for selecting items from
array.- Can be one of:
string: The string is used for matching against the contents of thearray. All strings or
objects with string properties in `array` that match this string will be returned. This alsoapplies to nested object properties.The predicate can be negated by prefixing the string with `!`.Object: A pattern object can be used to filter specific properties on objects contained
by `array`. For example `{name:"M", phone:"1"}` predicate will return an array of itemswhich have property `name` containing "M" and property `phone` containing "1". A specialproperty name (`$` by default) can be used (e.g. as in `{$: "text"}`) to accept a matchagainst any property of the object or its nested object properties. That's equivalent to thesimple substring match with a `string` as described above. The special property name can beoverwritten, using the `anyPropertyKey` parameter.The predicate can be negated by prefixing the string with `!`.For example `{name: "!M"}` predicate will return an array of items which have property `name`not containing "M".Note that a named property will match properties on the same level only, while the special`$` property will match properties on the same level or deeper. E.g. an array item like`{name: {first: 'John', last: 'Doe'}}` will **not** be matched by `{name: 'John'}`, but**will** be matched by `{$: 'John'}`.function(value, index, array): A predicate function can be used to write arbitrary filters.
The function is called for each element of the array, with the element, its index, andthe entire array itself as arguments.The final result is an array of those elements that the predicate returned true for.- @param {function(actual, expected)|true|false} [comparator] Comparator which is used in
determining if values retrieved using `expression` (when it is not a function) should beconsidered a match based on the expected value (from the filter expression) and actualvalue (from the object in the array).- Can be one of:
function(actual, expected):
The function will be given the object value and the predicate value to compare andshould return true if both values should be considered equal.true: A shorthand for strict value comparison.
This is essentially strict comparison of expected and actual.false: A short hand for a function which will look for a substring match in a case
insensitive way. Primitive values are converted to strings. Objects are not compared againstprimitives, unless they have a custom `toString` method (e.g. `Date` objects).- Defaults to
false. - @param {string} [anyPropertyKey] The special property name that matches against any property.
By default `$`.- */
3 - Collection filters
Read keys, values, and entries from objects and keyed collections.
The collection filters accept objects, Map, and other values that expose the
corresponding iterable method.
<li ng-repeat="name in team | keys">{{ name }}</li>
<li ng-repeat="member in team | values">{{ member }}</li>
<li ng-repeat="entry in team | entries">{{ entry.key }}: {{ entry.value }}</li>
null, undefined, primitives, and unsupported inputs produce an empty array.
Use entries when both the key and value are needed.
4 - JSON
Render a value as formatted JSON for inspection and debugging.
JSON filter
Description
Allows you to convert a JavaScript object into a JSON string.
This filter is mostly useful for debugging. When using the double curly
{{value}} notation, the binding is automatically converted to JSON.
Parameters
- object
{*}: Any JavaScript object (including arrays and primitive types) to filter. - spacing
{number=}: The number of spaces to use per indentation, defaults to 2.
Returns
{string}: JSON string.
5 - Date
Format dates with the browser’s locale-aware formatter.
The date filter accepts a Date, timestamp, or date string. It delegates to
Intl.DateTimeFormat, so locale and formatting options follow the browser
standard.
<time>{{ task.dueAt | date:'en-GB' }}</time>
A missing or invalid input produces an empty string. Store real dates or unambiguous timestamps in application state.
6 - Limit to
Return a bounded part of an array, string, or number.
Limit to filter
Description
Creates a new array or string containing only a specified number of elements.
The elements are taken from either the beginning or the end of the source array,
string, or number, as specified by the value and sign (positive or negative) of
limit. Other array-like objects are also supported (e.g., array subclasses,
NodeLists, JQLite/jQuery collections, etc.). If a number is used as input, it is
converted to a string.
Parameters
- input
{Array|ArrayLike|string|number}: Array/array-like, string, or number to be limited. - limit
{string|number}: The length of the returned array or string.- If the
limitnumber is positive,limitnumber of items from the beginning of the source array/string are copied. - If the number is negative,
limitnumber of items from the end of the source array/string are copied. - The
limitwill be trimmed if it exceedsarray.length. - If
limitis undefined, the input will be returned unchanged.
- If the
- begin
{(string|number)=}: Index at which to begin limitation. As a negative index,beginindicates an offset from the end ofinput. Defaults to0.
Returns
{Array|string}: A new sub-array or substring of lengthlimitor less if the input had less thanlimitelements.
7 - Number, currency, and percent
Format numeric values with locale-aware browser formatters.
AngularTS provides three filters backed by Intl.NumberFormat:
numberformats a finite number.currencyuses currency style and defaults to USD.percentuses percentage style.
<span>{{ total | number:'en-US' }}</span>
<span>{{ total | currency:'en-US' }}</span>
<span>{{ completion | percent:'en-US' }}</span>
Numeric strings are accepted. Missing, empty, infinite, and nonnumeric values produce an empty string. Supply an explicit locale and currency for user-facing output.
8 - Order by
Order a collection by one or more computed values.
Order by filter
Description
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:
- 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 thelabelproperty, would be transformed to:{ value: 'foo', type: 'string', index: ... }
Note: null values use ’null’ as their type. 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.
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.)
If a custom comparator still can’t distinguish between two items, then they will be sorted based on their index using the built-in comparator.
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:
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 later steps.) 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 later steps.) No conversion; the object itself is used. The Default Comparator The default, built-in comparator should be sufficient for most use cases. In short, it compares numbers numerically, strings alphabetically (and case-insensitively), for objects falls back to using their index in the original collection, sorts values of different types by type, and puts undefined and null values at the end of the sorted list.
More specifically, it follows these steps to determine the relative order of items:
If the compared values are of different types: If one of the values is undefined, consider it “greater than” the other. Else if one of the values is null, consider it “greater than” the other. Else compare the types themselves alphabetically. If both values are of type string, compare them alphabetically in a case- and locale-insensitive way. If both values are objects, compare their indices instead. 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 sorting, null and undefined are considered “greater than” any other value (with undefined “greater than” null). This effectively means that null and undefined values end up at the end of a list sorted in ascending order. Note: null values use ’null’ as their type to be able to distinguish them from objects.
Parameters collection {Array|ArrayLike}: The collection (array or array-like object) to sort.
expression {(Function|string|Array.<Function|string>)=}: A predicate (or list of predicates) to be used by the comparator to determine the order of elements.
Can be one of:
Function: A getter function. This function will be called with each item as an argument and the return value will be used for sorting. string: An AngularTS expression. This expression will be evaluated against each item and the result will be used for sorting. For example, use ’label’ to sort by a property called label or ’label.substring(0, 3)’ to sort by the first 3 characters of the label property. (The result of a constant expression is interpreted as a property name to be used for comparison. For example, use ‘“special name”’ (note the extra pair of quotes) to sort by a property called special name.) An expression can be optionally prefixed with + or - to control the sorting direction, ascending or descending. For example, ‘+label’ or ‘-label’. If no property is provided, (e.g., ‘+’ or ‘-’), the collection element itself is used in comparisons. Array: An array of function and/or string predicates. If a predicate cannot determine the relative order of two items, the next predicate is used as a tie-breaker. Note: If the predicate is missing or empty, then it defaults to ‘+’.
reverse {boolean=}: If true, reverse the sorting order.
comparator {(Function)=}: The comparator function used to determine the relative order of value pairs. If omitted, the built-in comparator will be used.
Returns {Array}: The sorted array.
9 - Relative time
Format relative dates such as tomorrow or three days ago.
The relativeTime filter delegates to Intl.RelativeTimeFormat. Its input is
an offset, not a timestamp. The unit defaults to day.
<span>{{ -1 | relativeTime:'day':'en' }}</span>
<span>{{ 2 | relativeTime:'hour':'en' }}</span>
Missing and nonnumeric values produce an empty string. Calculate the offset in the model so time-dependent updates have an explicit schedule.