Skip to main content

Filtering

You have 3,000 support tickets and need to find the ones assigned to Alice that were opened last week. Click the filter icon on "Assignee", pick Alice. Click the filter on "Created Date", set the range. Done — two clicks, no code.

Click the filter icon in a column header to filter
Live
Framework-Specific Styling

The demo uses React Radix styling. Each framework renders filter UI with its native components — dropdowns, date pickers, and inputs that match your design system.

Add filters to any column​

Set filterable on a column definition. The type field picks the filter UI:

import { OGrid } from '@alaarab/ogrid-react-radix';

const columns = [
{
columnId: 'name',
name: 'Name',
filterable: { type: 'text' },
},
{
columnId: 'department',
name: 'Department',
filterable: { type: 'multiSelect', filterField: 'department' },
},
{
columnId: 'status',
name: 'Status',
filterable: { type: 'multiSelect', filterField: 'status' },
},
{
columnId: 'salary',
name: 'Salary',
type: 'numeric' as const,
valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
},
];

function App() {
return (
<OGrid
columns={columns}
data={people}
getRowId={(item) => item.id}
defaultPageSize={10}
/>
);
}
Switching UI libraries

Same props across all React packages — just change the import:

  • Radix (lightweight, default): from '@alaarab/ogrid-react-radix'
  • Fluent UI (Microsoft 365 / SPFx): from '@alaarab/ogrid-react-fluent' - wrap in <FluentProvider>

Filter types​

Text filter​

A case-insensitive substring search. Good for names, descriptions, anything freeform:

{ columnId: 'name', name: 'Name', filterable: { type: 'text' } }

Type "john" and it matches "John Smith", "Johnny", and "Johnathan".

Multi-select filter​

A checkbox list — users pick one or more values, the grid shows only matching rows. Has built-in "Select All" and "Clear All" buttons.

{
columnId: 'status',
name: 'Status',
filterable: {
type: 'multiSelect',
filterField: 'status', // field to filter on (defaults to columnId)
optionsSource: 'static', // where options come from
options: ['Active', 'Draft', 'Archived'],
},
}

Where do the options come from?

optionsSourceHow it works
(omitted)Client-side: unique values extracted from your data. Server-side: calls your API.
'static'Uses the options array you provide — great for known enums.
'api'Calls dataSource.fetchFilterOptions(field) — for dynamic option lists.
'years'Auto-generates a year list from the current year down.

Any of, None of, All of​

Above the checkbox list, a match select sets how the chosen options apply:

ModeKeeps rows thatFilter value
Any of (default)hold one of the chosen options{ type: 'multiSelect', value: ['open'] }
None ofhold none of them (exclude, "not in"){ type: 'multiSelect', value: ['open'], mode: 'none' }
All ofhold every chosen option (array columns){ type: 'multiSelect', value: ['Ana', 'Ben'], mode: 'all' }

mode is left out for Any of, so existing saved filters keep working. Data sources receive mode in filters unchanged.

Columns with array values​

For a column whose value is an array (tags, reviewers), set multiValue: true. Each array item becomes an option, a row matches item by item, and the match select adds All of:

{
columnId: 'reviewers',
name: 'Reviewers',
valueFormatter: (v) => (Array.isArray(v) ? v.join(', ') : ''),
filterable: { type: 'multiSelect', multiValue: true },
}

An empty array counts as blank. Matching handles array values even without the flag; multiValue adds All of and keeps sorting off the Web Worker (workerSort) for that column.

Date filter​

A date range picker with "From" and "To" inputs. Shows only rows where the column value falls within the range:

{
columnId: 'createdDate',
name: 'Created',
type: 'date',
filterable: { type: 'date' },
}
tip

A column with type: 'date' automatically gets date formatting, chronological sorting, and a native date input editor — you don't need to configure those separately.

People filter​

A search-as-you-type lookup that hits your directory API. Designed for Microsoft Graph, LDAP, or any endpoint that returns users:

{
columnId: 'assignee',
name: 'Assignee',
filterable: { type: 'people' },
}
info

The people filter requires a dataSource with a searchPeople method that returns UserLike objects (name, email, optional photo).

Number and condition filters​

Excel's number, text and date filters ("custom AutoFilter"): pick an operator, type a value, and optionally add a second condition joined with And or Or.

{ columnId: 'salary', name: 'Salary', type: 'numeric', filterable: { type: 'number' } },
{ columnId: 'name', name: 'Name', filterable: { type: 'condition' } },
{ columnId: 'startDate', name: 'Start', type: 'date', filterable: { type: 'condition' } },

'number' always uses number operators. 'condition' picks the operator set from the column type: numeric columns get number operators, date columns get date operators, and everything else gets text operators.

Open the Age, Salary, Name or Start Date filter: try Top N, Between, or two conditions with Or
Live
OperatorsNumberTextDate
Equals / Does not equal✓✓✓ (Is on / Is not on)
Greater than, ≥, Less than, ≤✓✓ (Is after, Is on or after, Is before, Is on or before)
Between (inclusive)✓✓
Top N / Bottom N✓
Above average / Below average✓
Contains / Does not contain / Begins with / Ends with✓
Is blank / Is not blank✓✓✓

How values are compared:

  • Numbers: numeric text such as "1,200" counts as a number. Blank and non-numeric cells never match a comparison, but they do match Does not equal.
  • Text: case-insensitive, against the cell's raw value.
  • Dates: compared by calendar day (UTC), so Is on 2024-01-15 matches any time that day.
  • Blank: null, undefined, empty or whitespace-only text.
  • Top N, Bottom N and averages are computed over the whole column (all rows, before other columns' filters). Ties at the Nth value are included.

The filter value is plain, serializable data, so it works with controlled filters, getColumnState(), and server-side data sources:

const filters: IFilters = {
salary: {
type: 'condition',
value: {
kind: 'number',
conditions: [
{ operator: 'between', value: 50000, valueTo: 80000 },
{ operator: 'blank' },
],
join: 'or', // default 'and'
},
},
};

Incomplete conditions (no operand, an unparsable number or date) are ignored; a filter with none left is removed. The filter icon shows the active state, and Clear in the popover removes the filter.

quickFilterBox adds a search box to the start of the grid's toolbar. It searches every visible column at once and works on top of the column filters:

<OGrid columns={columns} data={reports} getRowId={(r) => r.id} quickFilterBox />
  • The text is split on spaces and every term must match somewhere in the row, in any visible column. carol signed keeps Carol's signed rows.
  • Matching is case-insensitive and checks both the raw value and the displayed text, so a budget shown as $1,200 matches 1200 and $1,200.
  • Hidden columns are not searched.
  • Typing applies after a short pause; Enter applies at once and Escape clears. A change goes back to page 1.

Pass an object to change the box's text: quickFilterBox={{ placeholder: 'Search reports' }} (also ariaLabel).

To keep the text yourself (URL sync, saved views, or your own search input), use quickFilter and onQuickFilterChange. Leave out quickFilterBox to drive the search from your own input:

const [search, setSearch] = useState('');

<input type="search" value={search} onChange={(e) => setSearch(e.target.value)} />
<OGrid columns={columns} data={reports} getRowId={(r) => r.id} quickFilter={search} />

With your own input, consider debouncing it for large grids; the built-in box already does.

To search text that isn't in a visible column (comments, notes, ids), return it from getQuickFilterText. Terms can match it like a column:

const getQuickFilterText = (report: Report) => report.comments.join(' ');

<OGrid quickFilterBox getQuickFilterText={getQuickFilterText} {...props} />

Passing a new function re-filters, so define it outside the component or wrap it in useCallback, and change its dependencies when what it returns changes. As with column filters, an edited row keeps its place until the filters, the search text or the getter change.

With a dataSource, the grid does not search rows itself: it passes the trimmed text to fetchPage (and windowed getRows / getRowCount) as quickFilter, and your server applies it.

Keeping filter state outside the grid​

By default the grid owns its filter state — filters reset when the component unmounts. To persist them (URL sync, page reload survival), pass filters and onFiltersChange:

function App() {
const [filters, setFilters] = useState<IFilters>({
status: { type: 'multiSelect', value: ['Active'] },
name: { type: 'text', value: 'John' },
});

return (
<OGrid
columns={columns}
data={tasks}
getRowId={(item) => item.id}
filters={filters}
onFiltersChange={setFilters}
/>
);
}

Now you can serialize filters to the URL, localStorage, or a server — and the grid will restore the exact filter state when the user comes back.

Saving filters in the URL​

Core has helpers so you don't hand-roll this (also exported from the React packages):

  • serializeFilters(filters): a compact string (JSON, sorted keys, empty entries dropped). Returns '' when nothing is filtered.
  • parseFilters(text, columns?): reads it back. Returns { filters, invalid } and never throws: bad JSON gives {}.
  • validateFilters(value, columns?): the same check for a value you already parsed.

Each entry is rebuilt from its known fields, and malformed ones are dropped and listed in invalid ({ field, reason }). Pass columns to also drop entries for fields that aren't filterable, or whose type doesn't match the column's filter (for example a text filter on a number column).

import { parseFilters, serializeFilters } from '@alaarab/ogrid-react-radix';

const [params, setParams] = useSearchParams();
const filters = useMemo(() => parseFilters(params.get('filters'), columns).filters, [params]);

<OGrid
columns={columns}
data={reports}
getRowId={(r) => r.id}
filters={filters}
onFiltersChange={(next) => {
const text = serializeFilters(next);
setParams((p) => {
if (text) p.set('filters', text);
else p.delete('filters');
return p;
});
}}
/>

The quick filter is a plain string, so store it as its own parameter (quickFilter / onQuickFilterChange).

Server-side filtering​

When you're using a dataSource, the grid hands off filter values to your fetchPage() function. You decide what to do with them — query params, request body, whatever your API expects:

const dataSource: IDataSource<Task> = {
fetchPage: async ({ filters, quickFilter, page, pageSize, sort }) => {
const params = new URLSearchParams({
page: String(page),
pageSize: String(pageSize),
});

if (filters.status?.type === 'multiSelect') {
params.set('status', filters.status.value.join(','));
}
if (filters.name?.type === 'text') {
params.set('search', filters.name.value);
}
if (filters.salary?.type === 'condition') {
// { kind, conditions: [{ operator, value, valueTo }], join }
params.set('salary', JSON.stringify(filters.salary.value));
}
if (quickFilter) {
// Search box text (quickFilter / quickFilterBox)
params.set('q', quickFilter);
}

const res = await fetch(`/api/tasks?${params}`);
return res.json(); // { items: Task[], totalCount: number }
},

// For 'api' option source on multiSelect filters:
fetchFilterOptions: async (field) => {
const res = await fetch(`/api/tasks/filter-options/${field}`);
return res.json(); // string[]
},

// For people filters:
searchPeople: async (query) => {
const res = await fetch(`/api/users/search?q=${query}`);
return res.json(); // UserLike[]
},
};
Pro tip

Server-side filtering pairs naturally with pagination. The totalCount in your fetchPage response tells the grid how many pages there are — so pagination stays accurate even when filters narrow the result set.

Props reference​

PropTypeDefaultDescription
filterableIColumnFilterDef—Set on IColumnDef. Enables the filter icon and defines the filter UI.
filterable.type'text' | 'multiSelect' | 'people' | 'date' | 'number' | 'condition'—Which filter UI to show.
filterable.filterFieldstringcolumnIdData field to filter on (useful when column key differs from data key).
filterable.optionsSource'api' | 'static' | 'years'autoWhere multi-select options come from.
filterable.optionsstring[]—Static option list for 'static' source.
filterable.yearsCountnumber—How many years to generate for 'years' source.
filtersIFilters—Controlled filter state (pass to own state externally).
onFiltersChange(filters: IFilters) => void—Called whenever filters change.
quickFilterBoxboolean | { placeholder?, ariaLabel? }falseShow the toolbar search box.
quickFilterstring-Controlled quick filter text.
defaultQuickFilterstring''Starting quick filter text when uncontrolled.
onQuickFilterChange(text: string) => void-Called when the search box changes the text.
getQuickFilterText(row: T) => string-Extra per-row text the quick filter searches (client-side).
filterable.multiValuebooleanfalseMulti-select on a column of arrays: options per item, adds All of.

Next steps​

  • Sorting — sort filtered results by any column
  • Pagination — paginate filtered results server-side or client-side
  • Server-Side Data — move all filtering, sorting, and paging to the server