Components

FilterBar

Filter controls for a list or table: applied-filter chips, a result count and one-click clear.

Storybook: Storybook
Source: Source

Installation

Package: @bigbang/ui
Import: import { FilterBar } from '@bigbang/ui';
Source: FilterBar.tsx
Storybook: FilterBar · Playground

FilterBar is in the @bigbang/ui package. Installation and style files are the same as for Button; see the Button code tab.

import { useState } from 'react';
import { FilterBar, type FilterField } from '@bigbang/ui';

type Filters = { query: string; status: string | null; category: string[]; mine: boolean };

const empty: Filters = { query: '', status: null, category: [], mine: false };

const fields: ReadonlyArray<FilterField<Filters>> = [
  { key: 'query', label: 'Search', kind: 'search' },
  { key: 'status', label: 'Status', kind: 'select', options: [{ value: 'active', label: 'Active' }] },
  { key: 'category', label: 'Category', kind: 'multi-select', options: [{ value: 'a', label: 'Category A' }] },
  { key: 'mine', label: 'Mine only', kind: 'toggle' },
];

function Page() {
  const [value, setValue] = useState(empty);
  return <FilterBar fields={fields} value={value} onValueChange={setValue} resultCount={12} />;
}

Props

valueRequired

Description: The applied filters, as a typed object. Keep it in state or in the URL and pass it back.
Type: Record<string, unknown>

onValueChangeRequired

Description: Called with the whole new value: on every change in instant mode, on Apply, on Clear and when a chip is removed in batch mode.
Type: (value: TFilter) => void

fieldsRequired

Description: The controls, in order. key names the property of value the control edits. kind is search (a string), select (a string or null), multi-select (a string array) or toggle (a boolean). The first search field is the search box; the other fields move under "More filters" on narrow screens.
Type: readonly FilterField<TFilter>[]

apply

Description: instant applies every change at once. batch keeps a draft and applies it with the Apply button, which is enabled only when the draft differs from value.
Type: 'instant' | 'batch'
Default: 'instant'

resultCount

Description: The number of results for the applied filters. Shown beside the chips and announced politely 500 ms after it stops changing.
Type: number

loading

Description: The results are being fetched: the count becomes a placeholder, the figure is aria-busy and Apply shows its loading state.
Type: boolean
Default: false

defaultValue

Description: The value "Clear filters" returns to. Without it every field is emptied.
Type: Record<string, unknown>

label

Description: Names the search region for screen readers. Defaults to the library string "Filtreler" or "Filters".
Type: string

className

Description: For layout only: margins and width.
Type: string

children

Description: Custom layout from the parts. Without it the bar lays out Search, More (with the other fields), Apply, Clear, Applied and ResultCount.
Type: ReactNode

FilterBar<TFilter> is generic: TFilter is inferred from value, and fields[].key accepts only keys of TFilter.

Field definition

FilterField<TFilter>: { key, label, kind, options?, placeholder? }. The value type is fixed by the kind:

`kind`	Type of `value[key]`	Counts as empty
`search`	`string`	`''` or only spaces
`select`	`string \| null`	`null` or `''`
`multi-select`	`string[]`	`[]`
`toggle`	`boolean`	`false`

Parts

Part	Props
`FilterBar.Search`	`name?`: the `key` of the search field; defaults to the first `search` field.
`FilterBar.Field`	`name`: the `key` of the field to draw.
`FilterBar.More`	`children`: the extra fields. Below 1024 px a button and a panel; above, part of the row.
`FilterBar.Apply`	Apply and Reset in `batch` mode; draws nothing in `instant` mode.
`FilterBar.Clear`	Only when a filter is applied.
`FilterBar.Applied`	The chips (Tag).
`FilterBar.ResultCount`	The count, when `resultCount` is set.

Parts work only inside <FilterBar> and throw outside it. With children the default layout is not drawn.

Data attributes

data-component="filter-bar", data-apply: on the root.
data-part: row, meta, field (with data-key and data-kind), more, panel, apply, reset, clear, applied, count.

URL sync

Two pure helpers write the filters to the address bar and read them back. The parameter name is the field key; a multi-select repeats the key, a toggle is true, and empty filters are left out.

import { filtersToSearchParams, searchParamsToFilters } from '@bigbang/ui';

const params = filtersToSearchParams(value, fields); // status=active&category=a&category=b
const restored = searchParamsToFilters(window.location.search, fields, empty);

searchParamsToFilters ignores option values that are not defined, so a hand-edited address cannot put an invalid value into the filters. Whether search text goes into the URL is the app’s decision; do not write searches that may contain personal data to the URL.