Filter Dropdown Component

Usage

Filter Dropdown is a complete filter control: a chip trigger that opens a popout list of options. Unlike the composition-first Filter Field — which hosts any content and tracks no value — Filter Dropdown has a built-in option list and owns its selection. Pass it options and listen for change.

import "@nordhealth/components/lib/FilterDropdown"

It ports the Provet Cloud filter dropdown and works alongside the other filter primitives in your filter toolbar.

Options

Options come in three shapes, which can be mixed:

Flat — { value, label, disabled? }.
Grouped — { heading, children: [...] }, rendered with a divider and heading.
Tree — a selectable option with children: the parent stays selectable and the children render indented beneath it.

Use options-value-key / options-label-key to read the value and label from different keys on your option objects.

Examples

Single select

In single-select mode the committed value is a string. Picking an option sets the value and closes the popout.

Multiple select

Add multiple for a multi-select. The value becomes an array of strings, each option shows a checkbox indicator, and the popout stays open after each selection.

Searchable

Add searchable for a search input at the top of the popout. By default options are filtered client-side by their label.

Grouped options

Pass groups ({ heading, children }) to cluster options under headings, separated by dividers.

Tree options

A selectable option with children becomes a tree: the parent stays selectable and the children render indented beneath it.

Select all

With multiple, add select-all for a control at the top of the popout that selects or deselects every option at once.

Clearable

clearable is on by default: a clear (✕) button appears while there is a selection. Pressing it clears the value (firing clear then change) without removing the dropdown.

Removable

Add removable so the trailing button clears the value and fires remove. Remove the whole dropdown from the DOM in the handler.

Loading

Set loading to show a spinner in the popout while asynchronous results load.

Async search

Set internal-search="false" for async search: the component stops filtering and emits search-change as the user types. Update options in the handler (and toggle loading).

Disabled

Set disabled to prevent interaction.

Accessibility

The trigger is a button associated with its popout via aria-controls, aria-haspopup and aria-expanded. The icon-only clear and remove buttons expose their purpose to assistive technology via visually-hidden labels.
The option list is a listbox with option children and aria-selected; in multiple mode it is aria-multiselectable. The active option is tracked for keyboard navigation.
Keyboard support: arrow keys move the active option, Home/End jump to the first/last, Enter selects, and Escape closes the popout.
The search input is labelled (the label is visually hidden) so it has an accessible name.

API reference

FilterDropdown

Filter Dropdown is a full-featured filter control: a chip trigger that opens a popout list of options. It owns its selection and tracks value, unlike the composition-first Filter Field — pass it options and listen for change. It ports the Provet Cloud filter dropdown. Options come in three shapes: a flat list ({ value, label }), groups ({ heading, children }) rendered with dividers, and tree-style options (a selectable option with children) where the parent stays selectable and the children render indented. Single mode tracks a string value and closes on select; multiple tracks an array, shows checkboxes and keeps the popout open.

<nord-filter-dropdown></nord-filter-dropdown>

Props

Property	Attribute	Description	Type	Default
`label`	`label`	The label naming what this filter targets, shown on the chip.	`string`	`''`
`name`	`name`	A name identifying what this dropdown filters, for form/identification.	`string`	`''`
`icon`	`icon`	The icon shown on the trigger.	`string`	`'interface-filter'`
`size`	`size`	The size of the trigger and popout. Defaults to `s` to match the other filter controls.	`FilterDropdownSize`	`'s'`
`optionsValueKey`	`options-value-key`	The key on each option object to read the value from. Defaults to `value`.	`string`	`'value'`
`optionsLabelKey`	`options-label-key`	The key on each option object to read the label from. Defaults to `label`.	`string`	`'label'`
`multiple`	`multiple`	Allows selecting more than one option. Selected options show a checkbox indicator and the popout stays open after each selection.	`boolean`	`false`
`searchable`	`searchable`	Shows a search input at the top of the popout to filter the options.	`boolean`	`false`
`internalSearch`	`internal-search`	Whether options are filtered client-side by their label. Defaults to `true`. Set to `false` for async search: the component then emits `search-change` and leaves filtering to the consumer (who updates `options`).	`boolean`	`true`
`selectAll`	`select-all`	Shows a "Select all" control at the top of the popout. Only applies with `multiple`.	`boolean`	`false`
`clearable`	`clearable`	Shows a clear (✕) button while there is a selection. Pressing it clears the value (firing `clear` then `change`) without removing the dropdown.	`boolean`	`true`
`removable`	`removable`	Whether the whole dropdown can be removed. When `true` the trailing affordance clears the value and fires `remove`; the consumer removes the dropdown from the DOM. Takes precedence over `clearable`.	`boolean`	`false`
`disabled`	`disabled`	Makes the component disabled. This prevents users from being able to interact with it and conveys its inactive state to assistive technologies.	`boolean`	`false`
`loading`	`loading`	Shows a spinner in the popout while asynchronous results are loading. Pair with `internal-search="false"` for async search.	`boolean`	`false`
`open`	`open`	Whether the popout is open. Set it to open or close the popout programmatically.	`boolean`	`false`
`noResultsMessage`	`no-results-message`	Message shown when no options match the search. Defaults to "No results.".	`string`	`''`
`labelForUnknown`	`label-for-unknown`	Fallback label shown for a selected value that has no matching option.	`string`	`''`

Methods

Method name	Parameters	Description
`show() => void`	N/A	Open the popout.
`hide() => void`	N/A	Close the popout.
`focus(options?: FocusOptions) => void`	`options`: FocusOptions	Focus the trigger button.

Event	Detail Type	Description
`change`	`FilterDropdownChangeEvent`	Dispatched when the committed selection changes via user interaction.
`search-change`	`FilterDropdownSearchChangeEvent`	Dispatched as the user types when `searchable` (use with `internal-search="false"` for async search).
`clear`	`FilterDropdownClearEvent`	Dispatched when the selection is cleared, before `change`.
`remove`	`FilterDropdownRemoveEvent`	Dispatched when the filter is removed (only when `removable`).
`load-more`	`FilterDropdownLoadMoreEvent`	Dispatched when the list is scrolled near its end (infinite scroll).
`open`	`NordEvent`	Dispatched when the popout is opened.
`close`	`NordEvent`	Dispatched when the popout is closed.

CSS Properties

CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.

Property	Description	Default
`--n-filter-dropdown-list-inline-size`	Controls the inline size, or width, of the popout list. Defaults vary by `size`.	`250px`

Light DOM & Tailwind. This component renders in the light DOM, so you can style it directly with your own CSS or Tailwind utility classes — there is no shadow boundary, and its default styles are low specificity, so your utilities win.

Dependencies

This component is internally dependent on the following components:

Filter Dropdown Light DOM & Tailwind