DropdownFilter

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

import { DropdownFilter } from "metricui";

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`	—	Label shown on the trigger button.
`options`*	`DropdownOption[] \| string[]`	—	Options to display. Pass string[] as shorthand — each string becomes { value: str, label: str }.
`value`	`string \| string[]`	—	Controlled selected value(s).
`defaultValue`	`string \| string[]`	—	Default value for uncontrolled mode.
`onChange`	`(value: string \| string[]) => void`	—	Change handler. Receives string in single mode, string[] in multiple mode.
`multiple`	`boolean`	`false`	Allow multiple selections.
`searchable`	`boolean`	`auto (true when > 8 options)`	Show search input inside dropdown.
`searchPlaceholder`	`string`	`"Search..."`	Placeholder text for search input.
`field`	`string`	—	FilterContext field name. When set, reads/writes to FilterContext dimensions.
`showAll`	`boolean`	`true (in multiple mode)`	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 config.
`className`	`string`	—	Additional CSS class names for the root element.
`classNames`	`{ root?, trigger?, dropdown?, option?, search? }`	—	Sub-element class overrides.
`id`	`string`	—	HTML id attribute.
`data-testid`	`string`	—	Test id for testing frameworks.

Data Shape

interface DropdownOption {
  value: string;       // Unique value
  label?: string;      // Display label (defaults to value)
  count?: number;      // Optional count badge
  icon?: ReactNode;    // Icon rendered before label
  group?: string;      // Group this option belongs to
}

Notes

DropdownFilter is UI only — it captures the selection, but does not filter data. You bring the data.
Without FilterProvider, use onChange for standalone mode. Context is optional.
Search is auto-enabled when there are more than 8 options. Override with searchable prop.
The 'All' option is shown by default in multiple mode. It clears all selections.
Grouped options render with section headers. Set the group property on each DropdownOption.
Uses forwardRef. Passes through id, data-testid, className, and classNames.
The aiContext prop (inherited from BaseComponentProps) adds business context for AI Insights analysis. See the AI Insights guide for details.