Filter Builder

Build one filter condition from a field, operator, and typed value in a joined control.

Interactive example

Each field declares its available operators and whether its value is selected, numeric, or text. Fields, operators, and options take an optional iconStart: an icon name, an icon descriptor, or a node.

{
  "fieldId": "answer-engine",
  "operatorId": "is",
  "value": "chatgpt"
}

Value types

  • select opens a selection menu. Set searchable when the option set benefits from filtering.
  • number renders an inline number input styled as the final button segment, commits on blur or Enter, and validates min, max, and step. Step alignment starts at min when provided and zero otherwise.
  • text renders an inline text input styled as the final button segment. Empty strings clear the value unless allowEmpty is enabled.
  • multi stores a string array and shows each value as a removable pill. Supply options for a checkable list, or allowCustom without options for a text input that adds a value on Enter or comma. Set onSearchChange to run the search yourself, for example against an API.

Compatible field changes

Changing the field preserves an operator when the new field contains the same operator ID. Otherwise, it uses defaultOperatorId or clears the operator.

Values reset by default. To preserve a value across related fields, give both value definitions the same compatibilityKey. The value is retained only when it is also valid for the new definition. For example, Assignee and Reviewer can share a user compatibility key.

Controlled state

FilterBuilder owns only which menu is open. The consumer owns the complete condition and updates it through onConditionChange.

Properties

fieldsRequired
readonly FilterBuilderField[]

Field definitions with their operators, icons, defaults, and value editor configuration.

conditionRequired
FilterCondition

Controlled fieldId, operatorId, and value. The value is a string, number, string array, or null.

onConditionChangeRequired
(condition: FilterCondition) => void

Called with the complete next condition after any segment changes.

fieldPlaceholder
string

Label shown before a field is selected.

Default: Select field

operatorPlaceholder
string

Label shown before an operator is selected.

Default: Select operator

valuePlaceholder
string

Fallback label shown before a value is configured or selected.

Default: Select value

showFieldSearch
boolean

Shows a search input in the field menu.

Default: false

fieldSearchPlaceholder
string

Placeholder for the optional field search input.

Default: Search fields

size
'micro''small''regular''large'

Shared size for the three joined segments.

Default: regular

disabled
boolean

Disables every segment in the condition.

Default: false

withRadixPortal
boolean

Controls portal rendering for the field, operator, and value menus.

Default: true

align
'start''center''end'

Aligns selection menus to their trigger segment.

Default: start

ariaLabel
string

Accessible label for the grouped filter condition.

Default: Filter condition

className
string

Additional classes for the joined control wrapper.

segmentClassNames
{ field?: string; operator?: string; value?: string }

Additional classes for each segment.