FilteringPlugin

Filtering Plugin for tbw-grid

Adds column header filters with text search, dropdown options, and custom filter panels. Supports both local filtering for small datasets and async handlers for server-side filtering on large datasets.

Installation

import { FilteringPlugin } from '@toolbox-web/grid/plugins/filtering';

Column Configuration

Property	Type	Description
filterable	boolean	Enable filtering for this column
filterType	'text' | 'select' | 'number' | 'date'	Filter UI type
filterOptions	unknown[]	Predefined options for select filters

CSS Custom Properties

Property	Default	Description
--tbw-filter-panel-bg	var(--tbw-color-panel-bg)	Panel background
--tbw-filter-panel-fg	var(--tbw-color-fg)	Panel text color
--tbw-filter-panel-border	var(--tbw-color-border)	Panel border
--tbw-filter-active-color	var(--tbw-color-accent)	Active filter indicator
--tbw-filter-input-bg	var(--tbw-color-bg)	Input background
--tbw-filter-input-focus	var(--tbw-color-accent)	Input focus border

Configuration Options

Option	Type	Description
debounceMs?	number	Debounce delay in milliseconds for the search input inside the default filter panel. Controls how long the panel waits after the user stops typing before re-filtering the unique values list.
caseSensitive?	boolean	Whether text-based filtering comparisons are case-sensitive.
trimInput?	boolean	Whether to trim leading/trailing whitespace from filter input values before applying them.
useWorker?	boolean	Whether to offload filtering to a Web Worker for large datasets.
filterPanelRenderer?	FilterPanelRenderer	Custom filter panel renderer that replaces the built-in panel content for all columns (unless you return undefined for specific columns to fall through to the next level).
trackColumnState?	boolean	Whether filter state should be included in column state persistence.
valuesHandler?	FilterValuesHandler	Async handler for fetching unique filter values from a server.
filterHandler?	FilterHandler<TRow>	Async handler for delegating filtering to a server.

Examples

Basic Usage with Filterable Columns

import { queryGrid } from '@toolbox-web/grid';
import { FilteringPlugin } from '@toolbox-web/grid/plugins/filtering';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name', filterable: true },
    { field: 'status', header: 'Status', filterable: true, filterType: 'select' },
    { field: 'email', header: 'Email', filterable: true },
  ],
  plugins: [new FilteringPlugin({ debounceMs: 300 })],
};
grid.rows = data;

Column Formatters in Filter Panel

When a column defines a `format` function, the built-in set filter panel
displays formatted labels instead of raw values. Search within the panel
also matches against the formatted text.
```ts
grid.gridConfig = {
  columns: [
    {
      field: 'price',
      filterable: true,
      format: (value) => `$${Number(value).toFixed(2)}`,
      // Filter checkboxes show "$9.99" instead of "9.99"
    },
  ],
  plugins: [new FilteringPlugin()],
};

### Server-Side Filtering with Async Handlers

```ts
new FilteringPlugin({
  // Fetch unique values from server for filter dropdown
  valuesHandler: async (field, column) => {
    const response = await fetch(`/api/distinct-values?field=${field}`);
    return response.json();
  },
  // Apply filters on the server
  filterHandler: async (filters, currentRows) => {
    const response = await fetch('/api/data', {
      method: 'POST',
      body: JSON.stringify({ filters }),
    });
    return response.json();
  },
});

See Also

• FilterConfig for all configuration options
• FilterModel for filter data structure
• FilterPanelParams for custom panel renderer parameters

Extends BaseGridPlugin

Inherited methods like attach(), detach(), afterRender(), etc. are documented in the base class.

Methods

setFilter()

Set a filter on a specific field. Pass null to remove the filter.

setFilter(field: string, filter: Omit<FilterModel, "field"> | null, options: object): void

Parameters

Name	Type	Description
field	string
filter	Omit<FilterModel, field> | unknown
options	object	{ silent: true } applies the filter without emitting filter-change

---

getFilter()

Get the current filter for a field.

getFilter(field: string): FilterModel | undefined

Parameters

Name	Type	Description
field	string

---

getFilters()

Get all active filters.

getFilters(): FilterModel[]

---

getFilterModel()

Alias for getFilters() to match functional API naming.

getFilterModel(): FilterModel[]

---

setFilterModel()

Set filters from an array (replaces all existing filters).

setFilterModel(filters: FilterModel[], options: object): void

Parameters

Name	Type	Description
filters	FilterModel[]
options	object	{ silent: true } applies filters without emitting filter-change

---

clearAllFilters()

Clear all filters.

clearAllFilters(options: object): void

Parameters

Name	Type	Description
options	object	{ silent: true } clears filters without emitting filter-change

---

clearFieldFilter()

Clear filter for a specific field.

clearFieldFilter(field: string, options: object): void

Parameters

Name	Type	Description
field	string
options	object	{ silent: true } clears filter without emitting filter-change

---

isFieldFiltered()

Check if a field has an active filter.

isFieldFiltered(field: string): boolean

Parameters

Name	Type	Description
field	string

---

getFilteredRowCount()

Get the count of filtered rows (from cache).

getFilteredRowCount(): number

---

getActiveFilters()

Get all active filters (alias for getFilters).

getActiveFilters(): FilterModel[]

---

getUniqueValues()

Get unique values for a field (for set filter dropdowns).

Prefers sourceRows (raw user input). When the user does not own the data (e.g. ServerSidePlugin is active and sourceRows is empty), falls back to the processed rows with placeholder/loading rows excluded so users get filter values for whatever has been loaded so far.

When a column has filterValue, individual extracted values are returned.

getUniqueValues(field: string): unknown[]

Parameters

Name	Type	Description
field	string

---

getStaleFilters()

Get set filters whose exclusion/inclusion list no longer matches any values in the current data, effectively selecting zero rows.

• notIn: stale when every current unique value is in the exclusion list (selected count = 0)
• in: stale when none of the included values exist in the current data

getStaleFilters(): FilterModel[]

---

getBlankMode()

Get the current blank mode for a field.

• 'all' — no blank filter active
• 'blanksOnly' — blank operator active
• 'nonBlanksOnly' — notBlank operator active

getBlankMode(field: string): BlankMode

Parameters

Name	Type	Description
field	string

---

toggleBlankFilter()

Toggle blank filter mode for a field.

Handles transitions:

• 'all' → clears the filter entirely
• 'blanksOnly' → sets blank operator, stashing any active filter in valueTo
• 'nonBlanksOnly' → sets notBlank operator, stashing any active filter in valueTo

When switching back to 'all', the stashed filter (if any) is restored.

toggleBlankFilter(field: string, mode: BlankMode): void

Parameters

Name	Type	Description
field	string
mode	BlankMode

---