Filter Item

Wraps one field component and reports its value to the surrounding nana-filter. The field is whatever you slot in — nana-input, nana-select, nana-combobox, nana-checkbox-group, nana-date-range, nana-range, nana-switch, or a native input / select.

Nothing about the field is re-implemented here. The item only reads its value, decides whether that value narrows the result set, and renders a label for the chip.

Import

import "@nana-tec/ui-components/filter-item";

Already registered if you imported @nana-tec/ui-components/filter.

Basic usage

<nana-filter-item name="status" label="Status" default-value="all">
  <nana-select value="all">
    <nana-option value="all">All</nana-option>
    <nana-option value="open">Open</nana-option>
  </nana-select>
</nana-filter-item>

How the value is read

Values are read by duck-typing, not by tag name, so a field this library does not ship works too — as long as it exposes value (or checked) and fires nana-change or change.

The slotted field	What the item reads
Has a boolean checked (switch, checkbox)	checked
Native <input type="checkbox"|"radio">	checked
Anything else	value

When a filter counts as active

Only active filters reach the aggregated value and earn a chip. Empty strings, empty arrays, null, and false are all inactive. A numeric 0 is not — it is a real filter value.

The case that catches people out is a select whose default option means “no filter”. Set default-value and the item stays inactive until the user moves off it:

<!-- Without default-value this shows a "Status: All" chip immediately. -->
<nana-filter-item name="status" default-value="all">…</nana-filter-item>

clear() returns the field to default-value when one is set, and to an empty value otherwise.

Chip text

The chip resolves option labels rather than showing raw values, so a chip reads Open orders, not open_unassigned. Arrays are joined; a nana-date-range value is split back into two readable ends. Override any of it with display.

<nana-filter-item name="tier" label="Tier" display="Enterprise only">…</nana-filter-item>

Live filtering

live also reports mid-edit (nana-input / input), not just on commit. Pair it with debounce on a search field so it filters as the user types without one request per keystroke.

Show code Copy

Values that are not filters

no-chip keeps an item out of the chip row, out of the active count, and out of Clear all, while still contributing to the value. Column pickers and sort selectors want this — they are part of the query, but the user does not mean to discard them when clearing filters.

<nana-filter-item name="columns" label="Visible columns" no-chip>
  <nana-checkbox-group orientation="horizontal">
    <nana-checkbox value="ref" checked>Ref</nana-checkbox>
    <nana-checkbox value="total">Total</nana-checkbox>
  </nana-checkbox-group>
</nana-filter-item>

API

Properties

Property	Attribute	Type	Default	Description
active	—	boolean	false	Reflected so the parent and consumer CSS can target items holding a value. Managed by the component; setting it by hand is overwritten on the next change.
debounce	—	number	0	Milliseconds to wait before reporting a change.
defaultValue	default-value	string | undefined	—	The value that means "no filter". An item sitting at its default is inactive, and `clear()` returns it here. Without this, any non-empty value counts as active — which makes a select defaulting to "All" look permanently filtered.
display	—	string | undefined	—	Chip text override. Derived from the value when unset.
grow	—	boolean	false	Let this item absorb the leftover width in a `bar` layout. Intended for the search field.
label	—	string	''	Human-readable name. Also becomes the control's accessible name when the field does not carry one of its own.
live	—	boolean	false	Also report while the user is still editing (`nana-input` / `input`), not only when the field commits. Pair with `debounce` for search fields.
name	—	string	''	Key this filter occupies in the parent's aggregated value object.
noChip	no-chip	boolean	false	Keep this item out of the chip row while still contributing to the aggregated value. Column pickers and sort selectors want this: they are part of the query but they do not narrow the result set, so rendering "Columns: Name, Status, Total" as a removable chip is misleading.
noLabel	no-label	boolean	false	Hide the label without losing it — it still names the control for assistive technology and still titles the chip.
operator	—	string	''	Relational hint rendered before the control and inside the chip — `is`, `contains`, `between`. Presentation only; no matching is performed here.
value	—	unknown	—	The field's current value. Assigning writes through to the field without emitting — the parent publishes one aggregated change instead.

Events

Event	Description
nana-filter-item-change	The field's value changed (`detail` is a `FilterState`)

Slots

Slot	Description
(default)	The field component this filter drives

CSS parts

Part	Description
::part(base)	The item wrapper
::part(label)	The label text
::part(operator)	The relational hint between label and control
::part(control)	The slotted field's container

CSS custom properties

Property	Description
--nana-filter-item-min-width	Minimum width before the item wraps
--nana-filter-item-gap	Gap between the label and the control

Accessibility

The label is forwarded to the slotted field as an aria-label, but only when that field has no accessible name of its own — a field with its own label keeps it. no-label hides the label visually without removing it from the accessibility tree or from the chip.