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';

Configuration Options

Option	Type	Default	Description
debounceMs	number	300	Debounce delay for filter input
caseSensitive	boolean	false	Case-sensitive string matching
trimInput	boolean	true	Trim whitespace from filter input
useWorker	boolean	true	Use Web Worker for datasets >1000 rows
filterPanelRenderer	FilterPanelRenderer	-	Custom filter panel renderer
valuesHandler	FilterValuesHandler	-	Async handler to fetch unique filter values
filterHandler	FilterHandler<TRow>	-	Async handler to apply filters remotely

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

Programmatic API

Method	Signature	Description
setFilter	(field, value) => void	Set filter value for a column
getFilters	() => FilterModel[]	Get all current filters
clearFilters	() => void	Clear all filters
clearFilter	(field) => void	Clear filter for a specific column

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

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). Uses sourceRows to include all values regardless of current filter. When a column has filterValue, individual extracted values are returned.

getUniqueValues(field: string): unknown[]

Parameters

Name	Type	Description
field	string

---