Improve this Doc View Source

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

## Usage

### In HTML Template Binding

    {{ filter_expression | filter : expression : comparator}}

### In JavaScript

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

### Arguments

Param | Type | Details
--- | --- | ---
array | Array | The source array.
expression | string Object function() | 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 `$` can be used (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 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)`: A predicate function can be used to write arbitrary filters. The function is called for each element of `array`. The final result is an array of those elements that the predicate returned true for.
comparator | function(actual, expected)true undefined | Comparator which is used in determining if the expected value (from the filter expression) and actual value (from the object in the array) should be considered a match. 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|undefined`: A short hand for a function which will look for a substring match in case insensitive way.

## Example

Edit in Plunker

    <div ng-init="friends = [{name:'John', phone:'555-1276'},
                             {name:'Mary', phone:'800-BIG-MARY'},
                             {name:'Mike', phone:'555-4321'},
                             {name:'Adam', phone:'555-5678'},
                             {name:'Julie', phone:'555-8765'},
                             {name:'Juliette', phone:'555-5678'}]"></div>

    Search: <input ng-model="searchText">
    <table id="searchTextResults">
      <tr><th>Name</th><th>Phone</th></tr>
      <tr ng-repeat="friend in friends | filter:searchText">
        <td>{{friend.name}}</td>
        <td>{{friend.phone}}</td>
      </tr>
    </table>
    <hr>
    Any: <input ng-model="search.$"> <br>
    Name only <input ng-model="search.name"><br>
    Phone only <input ng-model="search.phone"><br>
    Equality <input type="checkbox" ng-model="strict"><br>
    <table id="searchObjResults">
      <tr><th>Name</th><th>Phone</th></tr>
      <tr ng-repeat="friendObj in friends | filter:search:strict">
        <td>{{friendObj.name}}</td>
        <td>{{friendObj.phone}}</td>
      </tr>
    </table>

    var expectFriendNames = function(expectedNames, key) {
      element.all(by.repeater(key + ' in friends').column(key + '.name')).then(function(arr) {
        arr.forEach(function(wd, i) {
          expect(wd.getText()).toMatch(expectedNames[i]);
        });
      });
    };

    it('should search across all fields when filtering with a string', function() {
      var searchText = element(by.model('searchText'));
      searchText.clear();
      searchText.sendKeys('m');
      expectFriendNames(['Mary', 'Mike', 'Adam'], 'friend');

      searchText.clear();
      searchText.sendKeys('76');
      expectFriendNames(['John', 'Julie'], 'friend');
    });

    it('should search in specific fields when filtering with a predicate object', function() {
      var searchAny = element(by.model('search.$'));
      searchAny.clear();
      searchAny.sendKeys('i');
      expectFriendNames(['Mary', 'Mike', 'Julie', 'Juliette'], 'friendObj');
    });
    it('should use a equal comparison when comparator is true', function() {
      var searchName = element(by.model('search.name'));
      var strict = element(by.model('strict'));
      searchName.clear();
      searchName.sendKeys('Julie');
      strict.click();
      expectFriendNames(['Julie'], 'friendObj');
    });