Filtering

1. Decide when a change applies

Choose the timing by how the filter is used, not by its field type. Closing a filter never applies it. Cancel, Escape and clicking outside all discard the draft (the edits not yet applied).

Changing the operator applies at once, unless the new operator needs a value first. If a panel has its own Apply button, pass the panel’s draft to each filter. Don’t add a second Apply inside it.

2. Decide flat or grouped

With flat filters, every condition must match. An All group matches when every condition in it matches, and an Any group matches when at least one does. Use groups only when people need a query like “Active members who are in Design or have more than three projects”.

Build grouped queries with FilterBuilder. Keep the query as a draft until it’s applied, so results don’t change mid-edit.

Grouped conditions

{
  "kind": "group",
  "id": "root",
  "conjunction": "all",
  "children": [
    {
      "kind": "rule",
      "id": "status-rule",
      "field": "status",
      "operator": "is",
      "value": "active"
    },
    {
      "kind": "group",
      "id": "team-group",
      "conjunction": "any",
      "children": [
        {
          "kind": "rule",
          "id": "team-rule",
          "field": "team",
          "operator": "is",
          "value": "design"
        },
        {
          "kind": "rule",
          "id": "projects-rule",
          "field": "projects",
          "operator": "greaterThan",
          "value": "3"
        }
      ]
    }
  ]
}

To move from quick filters to a grouped query, convert each block’s value into one FilterBuilder rule. Each block’s example file exports its own conversion. FilterBuilder doesn’t re-check a block’s number limits.

3. Start from a minimal example

Each block page starts with a minimal example and the files to copy:

• ChoiceFilter: one value from a short list. Applies immediately.
• MultiChoiceFilter: several values. Applies with Apply.
• TextFilter: text. Applies with Apply.
• NumberComparisonFilter: one number against a threshold. Applies with Apply.
• NumberRangeFilter: a number between two ends. Applies with Apply.
• DateRangeFilter: a range of calendar days. Applies with Apply.

Lay several filters out with blocks/filtering/applied-filters.tsx. It wraps filters onto new lines as needed, and holds no filter state. If filters are edited in a separate panel, show the applied ones as removable chips:

4. Show the result states

Keep active filters visible while results load or fail. Show a different message for an empty list, no matches and a failed request. Retry keeps the filters.

Show the total count across all pages, and go back to page one when a filter changes. The result-state examples use native inputs, but the same states apply to the blocks.

Loading

Empty collection

No matches

Failure and retry

Examples

Team directory: immediate updates

Choosing a status or team updates the table at once. The filters have no Apply button.

Invoice list: Apply per filter

Each filter opens a checklist with its own Apply button. The trigger shows the applied values. Escape or clicking outside discards the changes.

These examples use sample data. The filtering blocks are experimental, so test them with your own data before you ship.

What your app owns

Your app owns the fields, permissions, values, filtering logic, requests, pagination and URL state. Cancel outdated requests and ignore late responses in your data layer.

Where to go next

• Components: FilterChip for a removal-only summary, FilterCondition for independently editable parts, FilterBuilder for grouped conditions.
• The source lives in packages/react/src/blocks/filtering and packages/react/src/patterns/filtering.