addColumnFilters

addColumnFilters filters table rows by specific column values.

Options

const table = createTable(data, {
  colFilter: addColumnFilters({ ... }),
});

const table = createTable(data, {
  colFilter: addColumnFilters({ ... }),
});

serverSide?: boolean

If true, filtering will not change vm.current.rows. Control filtering by updating the table’s data and use plugin state to drive your fetch.

Defaults to false.

matchMode?: 'self-or-descendants' | 'self'

How rows that have sub-rows (see addSubRows) are matched.

• 'self-or-descendants' keeps a row when it matches or when any of its descendants match, so a parent that does not match itself still appears above its matching children. This keeps the tree navigable but means a visible parent’s own cell values may fall outside the filter.
• 'self' requires every kept row to match on its own values. A parent that does not match is removed together with its subtree.

Defaults to 'self-or-descendants'.

Column Options

const columns = table.createColumns([
  table.column({
    header: 'Name',
    accessor: 'name',
    plugins: {
      colFilter: { ... },
    },
  }),
]);

const columns = table.createColumns([
  table.column({
    header: 'Name',
    accessor: 'name',
    plugins: {
      colFilter: { ... },
    },
  }),
]);

fn: ({ filterValue, value }) => boolean

Defines filter behavior for the column. Return true to keep the row.

render?: (renderProps) => RenderConfig

Renders a control on cell.current.props.[pluginName].render. renderProps extends TableState and includes:

• id: string
• filterValue: Box<any>: the column’s filter value; writing undefined clears it
• values: ReadonlyBox<any[]>: the column’s values after filtering
• preFilteredValues: ReadonlyBox<any[]>: the column’s values before filtering
• preFilteredRows: ReadonlyBox<BodyRow[]>

render is called once per header cell. Pass the boxes to your component and read their current there, so the control stays reactive:

render: ({ filterValue, values }) => createRender(TextFilter, { filterValue, values })

render: ({ filterValue, values }) => createRender(TextFilter, { filterValue, values })

<!-- TextFilter.svelte -->
<script lang="ts">
    import type { Box, ReadonlyBox } from '@humanspeak/svelte-headless-table'

    const { filterValue, values }: {
        filterValue: Box<string | undefined>
        values: ReadonlyBox<unknown[]>
    } = $props()
</script>

<input bind:value={filterValue.current} placeholder="Search {values.current.length} rows..." />

<!-- TextFilter.svelte -->
<script lang="ts">
    import type { Box, ReadonlyBox } from '@humanspeak/svelte-headless-table'

    const { filterValue, values }: {
        filterValue: Box<string | undefined>
        values: ReadonlyBox<unknown[]>
    } = $props()
</script>

<input bind:value={filterValue.current} placeholder="Search {values.current.length} rows..." />

initialFilterValue?: any

Initial filter value, applied when the view model is created.

Prop Set

HeaderCell props cell.current.props.colFilter

render: RenderConfig | undefined

The rendered filter component.

Interactions

• Filters on hidden columns still apply. addHiddenColumns removes the cell from row.cells, not from the row’s filter data, so a column-filter value keeps narrowing the rows while the column is hidden.
• With addExpandedRows, a sub-row is kept if it matches the filter itself or has a matching descendant (the default matchMode; use 'self' to drop non-matching parents). Register colFilter before expand so filtering happens before the tree is flattened; either order produces the same visible rows for a plain tree, but filtering first is cheaper.

Plugin State

const vm = table.createViewModel(columns)
const { pluginStates } = vm
const { filterValues } = pluginStates.colFilter

const vm = table.createViewModel(columns)
const { pluginStates } = vm
const { filterValues } = pluginStates.colFilter

filterValues: Box<Record<string, unknown>>

Active filter values by column id. Assign a new record to change them; a column without a value (or with undefined) is not filtered.

filterValues.current = { ...filterValues.current, status: 'single' }

filterValues.current = { ...filterValues.current, status: 'single' }

preFilteredRows: ReadonlyBox<BodyRow<Item>[]>

Rows before filtering.

Examples

filterValues.current = {
  "firstName": "",
  "lastName": "",
  "age": [
    null,
    null
  ],
  "visits": 0
}