W3cubDocs

/Angular.js 1.6

Improve this Doc View Source filter

  1. filter in module ng

Selects a subset of items from array and returns it as a new array.

Usage

In HTML Template Binding

{{ filter_expression | filter : expression : comparator : anyPropertyKey}}

In JavaScript

$filter('filter')(array, expression, comparator, anyPropertyKey)

Arguments

Param Type Details
array Array

The source array.

Note: If the array contains objects that reference themselves, filtering is not possible.
expression stringObjectfunction()

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 the array. All strings or objects with string properties in array that match this string will be returned. This also applies 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 items which have property name containing "M" and property phone containing "1". A special property name ($ by default) can be used (e.g. as in {$: "text"}) to accept a match against any property of the object or its nested object properties. That's equivalent to the simple substring match with a string as described above. The special property name can be overwritten, 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, and the entire array itself as arguments.

    The final result is an array of those elements that the predicate returned true for.

comparator
(optional)
function(actual, expected)truefalse

Comparator which is used in determining if values retrieved using expression (when it is not a function) should be considered a match based on the expected value (from the filter expression) and actual value (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 and should return true if both values should be considered equal.

  • true: A shorthand for function(actual, expected) { return angular.equals(actual, expected)}. 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 against primitives, unless they have a custom toString method (e.g. Date objects).

Defaults to false.

anyPropertyKey
(optional)
string

The special property name that matches against any property. By default $.

© 2010–2017 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://code.angularjs.org/1.6.5/docs/api/ng/filter/filter