Custom UI

The ready-made filter UI is built entirely on the hooks from @querycn/filter-react. Use them to build your own: a sidebar of checkboxes, quick-filter buttons, a different builder. The hooks handle the state, validation, the URL and the API request; you only render.

Need small changes? It's usually easier to edit the copied components.

Which hook do I need?Copy Anchor Link

All of them must be used inside a FilterProvider.

A minimal builderCopy Anchor Link

A panel with rule rows, using plain HTML elements:

import type { FilterRule } from "@querycn/filter-core"
import { useFilter, useFilterRule } from "@querycn/filter-react"

export function MyFilterPanel() {
  const { state, isDirty, addRule, apply, reset } = useFilter()
  return (
    <form onSubmit={(event) => { event.preventDefault(); apply() }}>
      {state.rules.map((rule) => <MyRuleRow key={rule.id} rule={rule} />)}
      <button type="button" onClick={() => addRule()}>Add filter</button>
      <button type="button" onClick={reset}>Clear all</button>
      <button type="submit" disabled={!isDirty}>Apply</button>
    </form>
  )
}

const MyRuleRow = React.memo(function MyRuleRow({ rule }: { rule: FilterRule }) {
  const { fields, operators, arity, setField, setOperator, setValue, remove } = useFilterRule(rule)

  return (
    <div>
      <select value={rule.field} onChange={(e) => setField(e.target.value)}>
        <option value="" disabled>Field</option>
        {fields.map((f) => <option key={f.name} value={f.name}>{f.label}</option>)}
      </select>
      <select value={rule.operator ?? ""} onChange={(e) => setOperator(e.target.value)}>
        <option value="" disabled>Operator</option>
        {operators.map((o) => <option key={o.id} value={o.id}>{o.label}</option>)}
      </select>
      {arity === "single" && (
        <input
          value={typeof rule.value === "string" || typeof rule.value === "number" ? rule.value : ""}
          onChange={(e) => setValue(e.target.value)}
        />
      )}
      <button type="button" onClick={remove}>×</button>
    </div>
  )
})

Draft and appliedCopy Anchor Link

The provider keeps two versions of the filter:

• The draft is what users are editing. Rules can be incomplete. useFilter and useFilterRule work on it.
• The applied filter is what's in the URL, and what your data follows. useAppliedFilter reads it.

apply() copies the complete draft rules to the applied filter. discard() throws the draft away and starts again from the applied filter; the ready-made popover calls it when closed without applying. The applied filter also changes on reset(), on a chip's ×, and when the URL changes (Back / Forward, a shared link).

FilterProviderCopy Anchor Link

import { FilterProvider } from "@querycn/filter-react"

<FilterProvider fields={orderFields} adapter={adapter}>
  {children}
</FilterProvider>

Define fields, serializer, messages and registry outside your components (or in useMemo). A new one on every render rebuilds everything.

useAppliedFilterCopy Anchor Link

The applied filter and what's built from it. Use it where you load or show data.

const { query, queryKey, activeCount } = useAppliedFilter()

With a custom serializer, pass its output type: useAppliedFilter<Prisma.OrderWhereInput>().

Outside a provider, it returns an empty filter instead of throwing, so a table can call it whether or not a filter is set up.

useFilterCopy Anchor Link

The draft and every editing action. It re-renders on each keystroke, so only use it in the editing UI.

Actions always read the latest draft, so setValue(…) followed by apply() in the same handler applies the new value.

useFilterActions() returns the same actions without state, isDirty and canAddRule. It doesn't change while users type, so memoized components that only need actions don't re-render.

useFilterRuleCopy Anchor Link

Everything one rule row needs, bound to that rule:

useRuleWarningsCopy Anchor Link

useRuleWarnings(rule) returns the warnings for one draft rule, like ["reversedRange"]. Get the text from messages.warnings[key]. It reads the draft, so use it in a small component of its own rather than in a memoized row.

useFieldOptionsCopy Anchor Link

Options for a select or multiSelect field, static or loaded from your API:

const { options, loading, error, query, search, retry, getLabel } = useFieldOptions(field, {
  selected: currentValues, // values that need a label
  enabled: open, // only load the list while the dropdown is open
})