Filtering, sorting and quick filter

API reference › Filtering, sorting and quick filter

grid.filters

grid.sort

grid.facets

A distribution chart in each column heading, which is also a filter control. Clicking a bar filters to that bucket; dragging across bars on an ordered column filters to the range. As filters are applied, the other columns' charts recount, so a dataset can be explored by clicking through headings rather than opening a dialog.

Off by default. The band roughly doubles the header's height.

facets: { enabled: true }                // grid-wide

// per column, layered over the grid's settings
{ field: 'price', type: 'number', facet: { strategy: 'quantile', buckets: 16 } }
{ field: 'notes', facet: false }         // opt one column out

A column is never counted against its own filter. Every other active filter applies; that column's own conditions are pruned out. Without this, clicking a bucket would collapse the chart to that single bar, leaving no way to see what was excluded or to widen the selection.

The filters are ordinary filters. They go through filters.set, so they undo, ride in saved views, and appear in whatever filter UI you already have. A drag emits a between range rather than a set of bucket indices, so it still means something after the data is replaced and the edges move.

Live streams suppress charts. Buckets that move under the pointer are worse than no chart, the control lies about what clicking it will do. Filters already made stay applied, because they are ordinary filters. Pausing the stream brings the charts back; set whilePaused: false if you would rather it did not.

Server-side sources need a provider. It receives the column, the current filter state with that column's own conditions removed, and the bucketing settings, and returns counts. Results are cached against the filter state, but this is still one query per column per filter change, a grid with eight faceted columns will ask eight questions every time a filter moves, and the backend has to be able to absorb that.

Charts are keyboard operable: focus enters from the header, arrows move between buckets, Enter toggles, Shift with arrows extends a range on ordered columns, Escape clears. Each bucket carries its range and count as an accessible name, and the chart as a whole carries a one-sentence description of the distribution's shape, which is the part bar-by-bar labels cannot convey.

Quick filter modes

One box, four ways to match. The mode persists until changed, so a host sets it once and goes on passing text alone.

grid.filters.quick('acme london', { mode: 'words' });
grid.filters.quickState();   // { text: 'acme london', mode: 'words' }

Filter grammar

The condition tree is a published wire protocol, not an internal shape. It serialises into saved state and travels to a remote source unchanged.

grid.filters.set({
  op: 'and',
  conditions: [
    { col: 'region', op: 'eq', value: 'EMEA' },
    { col: 'capacity', op: 'between', value: [100, 500], bounds: '[)' },
    { op: 'not', conditions: [
      { col: 'status', op: 'in', value: ['closed'] },
    ] },
  ],
});