Documentation

Quick Filter / Global Search

Quick Filter provides powerful global search functionality that searches across all columns with a single input. Choose between simple text matching or smart search mode with advanced operators for complex queries.

CodeSandbox

Basic Implementation

Enable quick filter by passing a quickFilter prop with a QuickFilterConfig object. The quick filter applies before column-specific filters in the filter chain.

Quick Filter Configuration

PropertyRequiredDescriptionExample
quickFilter
QuickFilterConfig
Optional
Enable global search/quick filter across all columns. Accepts a QuickFilterConfig object to control the search text, mode, case sensitivity, and which columns to search.

QuickFilterConfig Properties

QuickFilterConfig

PropertyRequiredDescriptionExample
text
string
Required
The search text to filter by. All columns will be searched for this text unless specific columns are configured.
mode
"simple" | "smart"
Optional
Search mode: 'simple' for basic contains matching, or 'smart' for advanced search with multi-word AND logic, phrase search (quotes), negation (minus), and column-specific search (column:value). Defaults to 'simple'.
caseSensitive
boolean
Optional
Whether the search should be case-sensitive. Defaults to false.
columns
Accessor[]
Optional
Array of column accessors to search. If not provided, all columns are searched (unless a column has quickFilterable: false).
useFormattedValue
boolean
Optional
Whether to search the formatted value (from valueFormatter) instead of the raw value. Defaults to false.
onChange
(text: string) => void
Optional
Callback function triggered when the quick filter text changes. Useful for tracking search analytics or syncing with external state.

Search Modes

Simple Mode

Simple mode performs basic text matching using a "contains" search. It's straightforward and intuitive for users who want to quickly find data without learning special syntax.

Example: Searching for engineering will match any row containing "engineering" in any searchable column.

Smart Mode

Smart mode provides advanced search capabilities with multiple operators for power users:

  • Multi-word (AND logic): alice engineering → matches rows containing both "alice" AND "engineering"
  • Phrase search: "alice johnson" → matches exact phrase "alice johnson"
  • Negation: -inactive → excludes rows containing "inactive"
  • Column-specific search: department:engineering → searches only in the department column
  • Combine operators: engineering -inactive location:new → complex queries with multiple conditions

Column Configuration

Customize how individual columns behave in quick filter searches using these HeaderObject properties:

Column Configuration

PropertyRequiredDescriptionExample
HeaderObject.quickFilterable
boolean
Optional
Controls whether this column should be included in quick filter searches. Set to false to exclude a column from global search. Defaults to true.
HeaderObject.quickFilterGetter
QuickFilterGetter
Optional
Custom function to extract the searchable value for this column. Useful for complex data structures, computed values, or custom search logic. Receives the row and returns a string or string array to search.

QuickFilterGetterProps

The quickFilterGetter function receives these properties:

QuickFilterGetterProps

PropertyRequiredDescriptionExample
row
Row
Required
The row data object.
accessor
Accessor
Required
The column accessor.
formattedValue
string | number | boolean | string[] | number[] | null | undefined
Optional
The formatted value if a valueFormatter is defined.

Programmatic Control

Control the quick filter programmatically using the tableRef.setQuickFilter() method. This is useful for implementing custom search UI, keyboard shortcuts, or integrating with external search components.

// Set quick filter text programmatically
tableRef.current?.setQuickFilter("engineering");

// Clear quick filter
tableRef.current?.setQuickFilter("");

// Keyboard shortcut example
useEffect(() => {
  const handleKeyPress = (e: KeyboardEvent) => {
    if (e.ctrlKey && e.key === 'f') {
      e.preventDefault();
      searchInputRef.current?.focus();
    }
  };
  window.addEventListener('keydown', handleKeyPress);
  return () => window.removeEventListener('keydown', handleKeyPress);
}, []);

For more details, see the Programmatic Control documentation.