Filtering

Note: we will always use the external grid filtering pattern.

UI-Grid allows you to filter rows. Just set the enableFiltering flag in your grid options (it is off by default).

Filtering can be disabled at the column level by setting enableFiltering: false in the column def. See the "company" column below for an example.

The filter field can be pre-populated by setting filter: { term: 'xxx' } in the column def. See the "gender" column below. Once the grid has rendered changes to the columnDef don't reflect in the grid - if they did then users would have their changes to filters overwritten every time the grid refreshed. If you want to programatically modify filters after initial render then modify grid.column[i].filters[0] directly.

Conditon

The filter object introduced above may also specify a condition, which defines how rows are chosen as matching the filter term. UI-Grid comes with several conditions out-of-the-box, which are defined by uiGridConstants.filter.*. See the "email" column below.

If no condition is set, UI-Grid will take a best guess based on the contents of the filter field. Even basic wildcard (*) use is supported!

If you want to create your own filtering logic, the condition field of the filter object can also be a function that gets run for each row. Such a function has the following signature:

function myCustomSorter(searchTerm, cellValue, row, column) {
  // Custom logic that returns true if `row`
  // passes the filter and false if it should
  // be filtered out
  return booleanResult;
}

For an example of this, see the "phone" column below for an example of this; the custom filter condition makes sure to strip the phone number of everything except digits to compare to the search term.

You can also optionally create a custom filter condition that doesn't require a term to be provided by the user - for example if you're matching to a variable that you're setting within your code. If you want to do this, you can set noTerm: true inside the filter, and the filter will run even when no term is provided. The filter box will, however, still be shown.

Placeholder

Set the placeholder property on the filter object to add a placeholder="" attribute to the inbput element. This is set for the "email" and "age" columns below.

Multiple filter fields

Occasionally, you may want to provide two or more filters for a single column. This can be accomplished by setting a filters array instead of a filter object. The elements of this array are the same as the contents of the filter object in all the previous examples. In fact, filter: { term: 'xxx' } is just an alias for filters: [{ term: 'xxx' }]. See the "age" column below for an example.

Date filters

The example also includes date filters. These work, however there isn't a date chooser in the filter widget - so you may need to implement a custom field if you want to filter dates in this way.

Dropdowns

Filtering supports dropdowns, in order to set a particular column to use a dropdown you should set: type: uiGridConstants.filter.SELECT and selectOptions: [ { value: 'x', label: 'decode of x' } , .... ]

If you need to internationalize the labels you'll need to complete that before providing the selectOptions array.

cellFilters

By default the filtering will not use the formatted value after applying cellFilters, it uses the raw value from the row. The filterCellFiltered columnDef option will cause filtering to be applied after the cellFilters are evaluated, as seen on the "Long Date" field.

External Filtering:

UI-Grid provides two functions that support this, firstly a filterChanged event that tells you when a user has changed their requested filter using the grid ui, and secondly a useExternalFiltering property to turn off the grid native filtering.