Filter.Form · ui.voila.dev

Recipient

Status

Customer

Sent

Price

Opened

<Filter.Form
	definitions={definitions}
	values={values}
	onValuesChange={setValues}
	locale="en-US"
/>;

API

Prop	Type	Default
`definitions`	`readonly FilterDefinition[]`	required	The filters to edit, in the order they are rendered.
`onValuesChange`	`(values: Readonly<Record<string, FilterValue>>) => void`	required	Called on every edit, not on an apply: `Filter.Form` is the editor without the commit step, so hold the record in your own state and decide when to query. For draft-then-apply, use `Filter.Root` or `Filter.Panel`.
`values`	`Readonly<Record<string, FilterValue>>`	required	The record being edited. Controlled — this component keeps no draft.
`labels`	`Partial<FilterLabels>`	—	Overrides for the strings the editor shows, merged over the surrounding filter root's (English defaults at the outermost level), so a partial is enough.
`locale`	`string`	—	BCP 47 tag used to format the numbers, money and dates; inherited when omitted.
`exit`	`Exit`	—	Inside a `<Presence>`: plays this child's way out before it unmounts.

Plus every <div> prop. Source: filter/components/filter-form.tsx.

Unlike Filter.Root, onValuesChange fires on every edit — there is no draft and no apply step. That is the point of this part: in a sidebar that filters as you type, a commit button would be in the way. In a panel the user has to dismiss, it would not.

Filter.Field

Prop	Type	Default
`definition`	`FilterDefinition`	required	The one filter to render. Its `kind` picks the editor.
`onValueChange`	`(value: FilterValue \| undefined) => void`	required	Called with `undefined` when the field is cleared, which is how a filter is removed.
`value`	`FilterValue \| undefined`	required	The current value, or `undefined` when this filter is not active.
`labels`	`Partial<FilterLabels>`	—	Overrides for the strings this field shows, merged over the surrounding filter root's (English defaults at the outermost level).
`locale`	`string`	—	BCP 47 tag used to format this field's numbers, money and dates; inherited when omitted.

Plus the DOM props of the element it renders. Source: filter/components/filter-field.tsx.

One filter on its own, which is what Filter.Form renders in a loop. Reach for it when a single filter belongs somewhere else on the page — a status select in a toolbar — rather than in the editor with the rest. Clearing it calls onValueChange with undefined, which is how a filter leaves the record.

A definition may carry renderPreview(value): whatever it returns renders under the field, fed the current (draft) value — a map of the area a radius covers, a count of what a range would match. The package stays domain-blind; the screen draws the preview.

Filter.Provider

Prop	Type	Default
`children`	`ReactNode`	—
`labels`	`Partial<FilterLabels>`	—	Overrides for the strings every part below shows, merged over the surrounding provider's (and, at the outermost level, over `defaultFilterLabels`), so a partial is enough.
`locale`	`string`	—	BCP 47 tag used to format numbers, money and dates; inherited when omitted.

Plus the DOM props of the element it renders. Source: filter/components/filter-provider.tsx.

Every part takes labels and locale itself, merged over the nearest provider's (English defaults at the outermost level), so a partial is enough. Wrap a screen in one provider when its parts sit apart in the tree — a bar in the header, a Filter.Dock beside the table — and give the copy once. A custom field reads it back with useFilterLabels() and useFilterLocale().