FilterBar

Structure

Two rows. The top row is the search Input, the "+ Filter" DropdownMenu that adds one field at a time, and an optional #trailing slot pushed to the right (a result count, an export button). The second row, the active-fields row, holds one control per visible field followed by a Clear button. It renders only while at least one field is visible: a field the user added from "+ Filter", or a pinned field. Clear itself shows only while it has something to do: a picked value, a non-pinned field still showing, or (with clearIncludesSearch) search text.

fields is a list of FilterFieldDef, a union on type. Every type shares key, label, icon? and pinned?:

const fields: FilterFieldDef[] = [
  // type omitted = 'select'. Multi-select by default; `searchable` swaps Select for Combobox.
  { key: 'severity', label: 'Severity', icon: 'i-lucide-triangle-alert', options: severityOptions },
  { key: 'owner', label: 'Owner', searchable: true, options: ownerOptions },
  // Single select: still stored as an array, with 0 or 1 entries.
  { key: 'branch', label: 'Branch', searchable: true, multiple: false, options: branchOptions },
  // On/off switch with its label inline. No options.
  { key: 'assignedToMe', label: 'Assigned to me', type: 'toggle', pinned: true },
  // Your own control, rendered from the #field-org slot.
  { key: 'org', label: 'Organization', type: 'custom' },
]

• select (the default): options is { value, label, icon?, description? }[]. description renders as a second line under the label, and a searchable field's Combobox matches search text against both label and description. multiple: false renders the picker in single mode. A searchable field also takes searchPlaceholder (its panel's search box) and virtualize (render only the visible rows, for hundreds of options).
• toggle: a Switch with the field's label next to it.
• custom: renders your #field-<key> slot in the active-fields row, for a control FilterBar can't own (a server-searched org picker, a date range). The slot receives { field, value, update }; call update(next) with the new string[] so Clear and the rest of the model stay consistent. FilterBar doesn't render a custom field's label, so the slot's control owns its accessible name (pass field.label as its aria-label or placeholder).
• pinned (any type): always in the active-fields row, never listed in "+ Filter", and Clear resets it to [] instead of removing it. When every field is pinned, the "+ Filter" button is hidden.
• defaultValue (any type): the value Clear resets the field to, for a list that always filters by something (a job state). Holding the default doesn't count as something to clear, so Clear only appears once the field holds anything else.

#option-leading="{ field, option }" replaces the leading icon of every option row in every select field's picker, for a status dot or badge. Branch on field.key when only some fields need it. #option-label="{ field, option }" replaces the label itself, for a badge that carries its own text. Either slot, once filled, replaces that part of every option in every select field's picker, so render the default yourself for the fields you don't decorate (<UIcon v-if="option.icon" :name="option.icon" /> or {{ option.label }} in a v-else).

loading renders Skeleton bars in place of the search input, the "+ Filter" button and each visible field's control during a first load. It only applies until loading first turns false, so you can pass the query's plain pending flag: a later reload (a filter change starting a fresh query) leaves the controls live and a picker the user is in never unmounts.

showSearch: false hides the search input for a list whose endpoint has no text search. clearIncludesSearch makes Clear also empty the search text; by default it only resets the filter fields, and the search box keeps its own clear button.

Value model

v-model is FilterValues, a Record<string, string[]> keyed by field key, for every field type, so the model never needs per-type handling:

A non-pinned key's presence (even as []) is what keeps its control in the row. Adding a field from "+ Filter" sets its key to []; Clear deletes every non-pinned key and sets every pinned key to []. Read values with filters.status?.length checks rather than 'status' in filters, since a present key can still be empty.

v-model:search updates on every keystroke, with no debounce. Debounce it yourself when the search drives a server request (for example refDebounced(search, 300) from VueUse); a client-side filter over data already loaded usually needs none.

Do

• Pair it with Table as the search-and-filter half of the Tables UI pattern - see the Tables UI pattern page for the full FilterBar → Table → footer composition.
• Mark a field searchable when its options list is long enough to need typing to narrow it (renders as Combobox); leave it off for a short, fixed list (renders as Select).
• Use multiple: false when only one value makes sense at a time (a branch, a single time window). Prefer searchable for a single-select field that users need to unset on its own: picking the selected option again in a Combobox clears it, while a single-mode Select can only swap its value, so Clear is the only way back to none.

Don't

• Don't expect a per-field remove affordance - an active field's chip stays until "Clear" removes every active field at once, or you clear it yourself; deselecting every value inside a field's own picker leaves that field's chip idle (0 selected) rather than auto-removing it.
• Don't expect the "+ Filter" menu to shrink as fields are added - every addable field stays listed, with an already-active one rendering checked and disabled instead of disappearing, so the full filterable set is always visible at a glance.
• Don't store a toggle or single-select value as a boolean or bare string in your own model - FilterBar always reads and writes string[].