Written by Huifer
I build TanStack Table admin tables in production, and filtering is the feature my users reach for first. When I add global search, column filters, and client-side sorting, I first decide what is data I already own in the browser and what is data a server must answer. Keeping that boundary explicit is what separates a fast filter box from a table that sends a request on every keystroke.
Official references: TanStack · TanStack Table filters guide · TanStack Table API reference · TanStack Query · web.dev performance · Cloudflare Workers · MDN
Last updated: 2026-10-31 · Changelog
TanStack Table Filtering: Global Search, Column Filters & Client-Side Sorting
TanStack Table filtering works by having the table read your column schema and filter definitions, then compute which rows pass. You configure global filter (one search box across all columns), column filters (per-column conditions), and sorting (column-driven ordering) through the TableOptions. This guide is for React developers deciding whether to implement filtering in an existing app or pick a SaaS template whose data table already ships this behavior. If the surrounding stack and data layer matter, you can compare SaaS templates and boilerplates before you write any filter code.
TL;DR
- Column filters use a
<input/>(or select) that mutates a column's filter value;getFilteredRowModel()applies the result.- Global filtering runs one search text across all searched columns via
filterFnsand thefilterFncolumn option.- Keep filtering and sorting client-side when the full dataset is already loaded; move to server-side when rows are paginated or permission-scoped.
- Combine client-side filtering with sorting on large local datasets inside a memoized
useMemopipeline.- Do not trust fuzzy/highlights blindly: verify row counts and null handling because TanStack Table treats
undefinedandnulldifferently.
Standalone answer: TanStack Table gives you the state, column options, and row models for filtering and sorting, but it does not fetch data. You configure enableColumnFilters, globalFilterFn, column-level filterFn, and sorting options, then supply getFilteredRowModel() and getSortedRowModel(). When rows live behind an API, replace client-side row models with server-driven parameters and keep data fetching in a state container such as TanStack Query.
Why filtering and sorting are the two features users notice first
A data-rich interface is judged by how quickly a user can find the row they care about. In my own admin tables, search and column filters cut the time to a specific record from scrolling to a typed query. The TanStack Table filters guide frames it correctly: filtering is a row-model concern, separate from how rows reach the browser. Sorting is the same category—it reorders already-available rows. When you understand that, you stop treating search as "a query call" and start treating it as "a purview of the client-side row model."
What "headless" actually means for filtering
Headless means the library exposes state + logic but zero markup. You render the input; you decide when the column-filter UI appears. This is a strength: a native <input type="search"> that you render yourself is accessible and stays inside your design system. TanStack Table then re-runs the row model on every filterValue change and exposes instance.filteredRows and instance.getRowMeta() for the count you need to show.
Before and after in a real table
Before: I put a text query in a <select> and re-fetched the whole API response on every change, hitting 200–400 ms of perceived lag and inconsistent results when pagination reset.
After: I added a client-side globalFilter with getFilteredRowModel() over the already-loaded page so keystrokes returned instantly, then pushed sorting into a useMemo.
Result: The filter box is responsive, and I only send a server request when the user intentionally changes pages or a column filter that genuinely lives server-side. I did not attach a benchmark to this guide; these are implementation expectations, not measured latency claims.
Setting up column filters and global search
Column filters are enabled per table and per column. You control both the UI and the value type with ColumnFiltersState. Global search is a single piece of text compared against the columns you opt into with the filterFn column option. The two coexist: global search is broad, column filters are narrow.
Enabling column filtering with a controlled input
import { useReactTable, getCoreRowModel, getFilteredRowModel, ColumnFiltersState } from '@tanstack/react-table'
export function UsersTable({ data }: { data: User[] }) {
const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
const table = useReactTable({
data,
columns,
state: { columnFilters },
onColumnFiltersChange: setColumnFilters,
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
// enable column filter UI only where you allow it
enableColumnFilters: true,
})
const nameFilter = table.getColumn('name')
return (
<div>
<input
placeholder="Filter by name"
value={(nameFilter?.getFilterValue() as string) ?? ''}
onChange={(e) => nameFilter?.setFilterValue(e.target.value)}
/>
<table>
{table.getHeaderGroups().map((hg) => (
<tr key={hg.id}>
{hg.headers.map((h) => h.isPlaceholder ? null : <th key={h.id}>{h.column.columnDef.header}</th>)}
</tr>
))}
{table.getRowModel().rows.map((row) => (
<tr key={row.id}>{row.getVisibleCells().map((cell) => <td key={cell.id}>{cell.getValue()}</td>)}</tr>
))}
</table>
</div>
)
}
The three pieces that make this work are onColumnFiltersChange, getFilteredRowModel(), and reading/writing the filter value through column.setFilterValue(). If you forget getFilteredRowModel(), the column filter state changes but rows are never re-evaluated.
Global search across several columns
import { useReactTable, getCoreRowModel, getFilteredRowModel, getSortedRowModel } from '@tanstack/react-table'
const columns = [
{ accessorKey: 'name', filterFn: 'includesString' },
{ accessorKey: 'email', filterFn: 'includesString' },
{ accessorKey: 'status', filterFn: 'equalsString' },
]
export function SearchableTable({ data }: { data: User[] }) {
const [globalFilter, setGlobalFilter] = useState('')
const table = useReactTable({
data,
columns,
state: { globalFilter },
onGlobalFilterChange: setGlobalFilter,
globalFilterFn: 'includesString',
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
getSortedRowModel: getSortedRowModel(),
})
return (
<input
value={globalFilter}
onChange={(e) => setGlobalFilter(e.target.value)}
placeholder="Search all columns"
/>
)
}
Column-level filterFn decides which columns the global text scans. 'includesString' matches case-sensitively; use 'includesStringSensitive' only when casing matters. The default globalFilterFn is auto, which picks a type-appropriate function—handy but less predictable than declaring it.
The client-side vs. server-side filtering boundary
This is the single most useful decision in a TanStack Table implementation, and the TanStack Table filters guide is explicit that both modes exist. Client-side filtering works because getFilteredRowModel() operates on in-memory rows. Server-side filtering means the table sends filtering query parameters to the API and renders what comes back—which means the row models for filtering are effectively no-ops on the client.
A decision checklist
| Concern | Client-side filtering | Server-side filtering |
|---|---|---|
| Dataset size | Fits comfortably in memory | Large, paginated, or tenant-scoped |
| Search latency | Instant (no network) | Depends on API round-trip |
| Consistency with list page | Good enough | Matches backend rules from the source of truth |
| Permission / tenant scoping | Risky if rules live server-side | Required when rows are filtered by ownership |
| Sort across full set | Only sorts loaded rows | Sorts across the entire backend dataset |
| Typical use | Admin panel overlaying a fetched page | Enterprise data tables, audit logs, dashboards |
When I keep filtering client-side, I also keep sorting client-side by composing both row models in one useReactTable call: getFilteredRowModel() before getSortedRowModel() so filtering and sorting each run where their metadata is valid. Sorting a small visible page is fine for one screen; sorting a 200k-row export belongs on the server.
Combining filtering, sorting, and pagination
const table = useReactTable({
data,
columns,
state: { columnFilters, sorting },
onColumnFiltersChange: setColumnFilters,
onSortingChange: setSorting,
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
getSortedRowModel: getSortedRowModel(),
getPaginationRowModel: getPaginationRowModel(),
initialState: { pagination: { pageSize: 25 } },
})
The order of the row models in the options object is the order they compose. Keep this exact sequence for the common case: filter, then sort, then paginate. If you move getPaginationRowModel() before filtering, the page chunks first and your filter only ever sees one page—a subtle bug that produces "missing" rows.
Custom filter functions and the null-value gotcha
TanStack Table ships a set of built-in filterFns (includesString, equalsString, inNumberRange, arrIncludes, equals, and more). When the defaults don't fit, define a custom function that returns a boolean for each row. The trap I hit most often is null handling: TanStack Table's built-in functions treat null and undefined differently, so a column full of nulls can silently vanish from search results.
A custom case-insensitive contains filter that is null-safe
const customContains: FilterFn<User> = (row, columnId, filterValue) => {
const value: unknown = row.getValue(columnId)
if (filterValue == null || filterValue === '') return true
if (value == null) return false
return String(value)
.toLowerCase()
.includes(String(filterValue).toLowerCase())
}
Attach it in the column definition with filterFn: customContains, or register it globally under filterFns on the table options. Because filterValue comes from your input as a string, coerce types explicitly—a numeric column filter that arrives as "42" needs Number() or it never matches. I scope custom functions narrowly and document the accepted value type so the next person reading the schema is not surprised.
Performance considerations and the server-side escape hatch
Filtering a few hundred rows is trivial. Filtering tens of thousands in a single render is where you must be honest about per-keystroke cost. getFilteredRowModel() re-runs on every filter change; that is fine for small lists, but for large local datasets I wrap data + filter states in a single useMemo and keep the raw table below the hot loop. The web.dev performance guide is a good reference for the rendering and memoization reasoning behind that pattern.
When to push filtering to the server
Move filtering server-side when any of these are true: the dataset is paginated, row access is permission-scoped by tenant, the filter involves a join the client simply lacks, or you need a stable total count. In the server model, columnFilters becomes query parameters (?name__contains=...), and TanStack Table's onColumnFiltersChange is the bridge that keeps the UI stateful while a route or a query key carries the needle to the API. I pair this with TanStack Query so the query key contains the filter values and navigation restores them.
Which template fits this use case?
Obtaining filtering, sorting, and pagination for free is one reason a developer picks a boilerplate instead of wiring a table from scratch. Rather than route every reader to one page, match the decision to the surrounding stack: if you are evaluating full-stack starting points, the SaaS boilerplate comparison shows what data-layer behavior ships out of the box; if you specifically want a pre-configured TanStack data table inside a starter, the TanStack templates catalog is the better destination. For pricing and license trade-offs, the template pricing and license terms page details what you pay and what you may do with it.
Before you choose: confirm that the template's table is client-side filtered on a loaded page (typical for admin dashboards) or server-side filtered through a data layer, and whether the volume you expect matches that model. I would not shift to server-side filtering just to copy a feature flag; make the choice on your dataset and per-row permission needs.
Related reading: Tanstack Db 1 0 Rc1 Whats New And Upgrade Guide · Tanstack Table Audit Log D1 Cursors · Tanstack Start Guide 20260711 Comprehensive
FAQ
Does TanStack Table filter a server response automatically?
No. Filtering operates on the rows you give the row model. If your data comes from an API, you must either fetch it fully and filter client-side, or send the filter state to the server and apply getFilteredRowModel() only over the returned page.
What is the difference between global filter and column filters?
Global filter is one text value compared across the columns you opted into with filterFn and the shared globalFilterFn. Column filters are per-column filterValues, each with its own function, usually driven by a dedicated input under each header.
Why does my filter show no results?
The most common causes are a missing getFilteredRowModel(), a column filter applied before getPaginationRowModel() so only one page is scanned, or a type mismatch where the filter arrives as a string but the accessor returns a number or null.
Should I debounce global search? Only if every keystroke triggers a server request. For pure client-side filtering over loaded data, debouncing adds delay without benefit. If the value feeds a query key, paginate the debounce so URL and fetch stay in sync.
Is sorting client-side accurate across all rows?
Only within the rows loaded into the table. getSortedRowModel() orders the current dataset; a page of data sorts that page, not the entire backend. For complete accuracy, sort server-side and drive sorting through a query parameter.
Disclosure and limitations: I run TanStack Table in production but have not attached a measured benchmark to this guide. Filtering, sorting, and performance expectations above are implementation guidance from TanStack official documentation and my own usage; treat row counts, latency, and null-behavior claims as calculated or estimated until verified in your environment. Rows may vary with dataset size, browser, and network. Details such as per-feature availability in a specific template are user-provided or [needs source] and should be confirmed against the latest release notes. All file paths and filterFn names reflect the current TanStack Table API at the time of writing; verify against the latest docs if something drifts. No material connection exists in this article.
Summary: filter what you already own client-side with getFilteredRowModel() and getSortedRowModel(), and push to the server the moment rows are paginated, permission-scoped, or sourced from a join. Compare how templates handle this boundary before you build it yourself.