Filters

DropdownFilter

A single or multi-select dropdown for dimension filtering. Supports search, grouped options, count badges, and FilterContext integration.

Use DropdownFilter to let users filter by a dimension — region, plan, status, etc. It's pure UI— it captures the user's selection and exposes it via context, but never touches, fetches, or filters your data. You read the active selection and pass it to your own data-fetching logic. See the Filtering guide for the full architecture.

Basic Example

A simple single-select dropdown. Click an option to select it — the dropdown closes automatically.

<DropdownFilter
  label="Region"
  options={[
    { value: "us", label: "US" },
    { value: "eu", label: "EU" },
    { value: "apac", label: "APAC" },
    { value: "latam", label: "LATAM" },
  ]}
/>

Multi-Select

Enable multiple to allow selecting more than one option. The dropdown stays open while selecting. Count badges show how many items belong to each option.

<DropdownFilter
  label="Plan"
  options={[
    { value: "free", label: "Free", count: 8421 },
    { value: "starter", label: "Starter", count: 2156 },
    { value: "pro", label: "Pro", count: 1089 },
    { value: "enterprise", label: "Enterprise", count: 312 },
  ]}
  multiple
  showAll
/>

Searchable

Search is enabled automatically when there are more than 8 options, or you can force it with searchable. The search input filters by label and value.

<DropdownFilter
  label="Country"
  options={countries}  // 24 countries
  searchable
/>

Grouped Options

Set a group property on each option to organize them under section headers.

<DropdownFilter
  label="Region"
  options={[
    { value: "us", label: "United States", group: "Americas" },
    { value: "ca", label: "Canada", group: "Americas" },
    { value: "gb", label: "United Kingdom", group: "Europe" },
    { value: "de", label: "Germany", group: "Europe" },
    { value: "jp", label: "Japan", group: "Asia-Pacific" },
    { value: "au", label: "Australia", group: "Asia-Pacific" },
  ]}
  multiple
  searchable
/>

Connected (FilterProvider)

When you set the field prop, DropdownFilter reads and writes to FilterContext dimensions. Any component can read the active value via useMetricFilters().dimensions[field].

useMetricFilters() output

dimensions.region: []

import { FilterProvider, useMetricFilters, DropdownFilter } from "metricui";

function Dashboard() {
  return (
    <FilterProvider>
      <DropdownFilter
        label="Region"
        options={regions}
        field="region"
        multiple
        showAll
      />
      <MyContent />
    </FilterProvider>
  );
}

function MyContent() {
  const filters = useMetricFilters();
  const regions = filters?.dimensions?.region ?? [];
  // Use regions to fetch/filter data
  return <div>Regions: {regions.join(", ")}</div>;
}

Interactive Controls

Experiment with multiple, searchable, showAll, and dense toggles.

Multiple

Searchable

Show All

Dense

Standalone (onChange)

Use onChange without a FilterProvider for simple use cases where you just need the selected value.

No selection yet

<DropdownFilter
  label="Region"
  options={regions}
  onChange={(value) => {
    console.log("Selected:", value);
    // Fetch data for this selection
  }}
/>

Props

Prop	Type	Default	Description
`label`	`string`	`(required)`	Label shown on the trigger button.
`options`	`DropdownOption[] \| string[]`	`(required)`	Options to display. Pass string[] as shorthand.
`value`	`string \| string[]`	`—`	Controlled selected value(s).
`defaultValue`	`string \| string[]`	`—`	Default value for uncontrolled mode.
`onChange`	`(value) => void`	`—`	Change handler. Receives string (single) or string[] (multiple).
`multiple`	`boolean`	`false`	Allow multiple selections.
`searchable`	`boolean`	`auto`	Show search input. Default: true when > 8 options.
`searchPlaceholder`	`string`	`"Search..."`	Placeholder text for search input.
`field`	`string`	`—`	FilterContext field name. Reads/writes to dimensions.
`showAll`	`boolean`	`true (multi)`	Show 'All' option that clears selection.
`allLabel`	`string`	`"All"`	Label for the All option.
`maxHeight`	`number`	`280`	Max height of dropdown in px.
`dense`	`boolean`	`false`	Compact mode. Falls back to MetricProvider.
`className`	`string`	`—`	Additional CSS classes.
`classNames`	`{ root?, trigger?, dropdown?, option?, search? }`	`—`	Sub-element class overrides.
`id`	`string`	`—`	HTML id.
`data-testid`	`string`	`—`	Test id.

Notes

DropdownFilter is UI only — it captures the user’s selection and exposes it via context or onChange, but never filters your data.
Without a FilterProvider, DropdownFilter still works via onChange. Context is optional.
Search is auto-enabled when there are more than 8 options. Override with the searchable prop.
The 'All' option is shown by default in multiple mode. It clears all selections.
Grouped options are rendered with section headers. Set the group property on each DropdownOption.
DropdownFilter uses forwardRef and passes through id, data-testid, className, and classNames.
Dense mode can be set per-component or inherited from MetricProvider.
The dropdown closes on outside click and on single-select option click.