Configuration (Config)

The FilterProvider accepts a config prop with the following shape:

type FilterConfig = {
  fields: FilterFieldDefinition[];
  maxRows?: number;
  allowConjunctionToggle?: boolean;
  paramStyle?: "underscore" | "bracket" | "custom";
  paramPrefix?: string;
  searchParamName?: string;
  locale?: Locale;
  customParamBuilder?: (rows: FilterRow[]) => URLSearchParams;
};

Config Properties

Property	Type	Default	Description
`fields`	`FilterFieldDefinition[]`	Required	The list of fields available for filtering.
`maxRows`	`number`	`10`	Maximum number of filter rows a user can add.
`allowConjunctionToggle`	`boolean`	`true`	Allows the user to toggle between `AND` / `OR` for the whole query.
`paramStyle`	`"underscore" \| "bracket" \| "custom"`	`"underscore"`	Determines how the query string is formatted in the URL.
`paramPrefix`	`string`	`undefined`	Optional prefix appended to all filter query parameters (e.g. `filter_`).
`searchParamName`	`string`	`"q"`	The URL parameter name used for global search. Used by `FilterBar`.
`locale`	`Locale`	`enUS`	A `date-fns` locale object used to format the date picker.
`customParamBuilder`	`Function`	`undefined`	Required when `paramStyle` is `"custom"`.

Param Style Examples

Given a filter of price > 100:

Style	Output
`underscore`	`?price_gt=100`
`bracket`	`?price[gt]=100`
`custom`	Whatever your custom builder returns

Example: Custom Param Builder

tsx

<FilterProvider
  config={{
    fields: myFields,
    paramStyle: "custom",
    customParamBuilder: (rows) => {
      const params = new URLSearchParams();
      for (const row of rows) {
        params.set(`filter[${row.field}][${row.operator}]`, row.value);
      }
      return params;
    },
  }}
>
  <FilterRoot />
</FilterProvider>

FilterBar Props

If you use the <FilterBar /> wrapper instead of just the bare <FilterRoot />, you can configure the search input and the layout order directly on the FilterBar component.

Property	Type	Default	Description
`searchPlaceholder`	`string`	`"Search..."`	Placeholder text for the search input.
`searchValue`	`string`	`undefined`	Optional external controlled state for the search input.
`onSearchChange`	`(value: string) => void`	`undefined`	Optional callback when search value changes. Overrides default URL sync behavior.
`hideSearch`	`boolean`	`false`	Hides the search input entirely.
`layout`	`"search-filters" \| "filters-search"`	`"search-filters"`	Reverses the layout order of the Search Input and Filter button.

tsx

<FilterBar 
  searchPlaceholder="Search models..." 
  layout="filters-search" 
/>