FilterBar

A container component for dashboard filters with auto-generated FilterTags, badge slot, collapsible accordion, active filter count, and clear-all.

import { FilterBar } from "metricui";

Use FilterBar as the single home for all dashboard filters. Drop DropdownFilter, PeriodSelector, and SegmentToggle inside, and FilterBar handles layout, tag display, collapse/expand, and the "Clear all" button automatically. It must be inside a FilterProvider.

Basic Example

Drop filter components directly as children. Without FilterBar.Primary / FilterBar.Secondary, all children go into the primary row.

Filters

<FilterProvider>
  <FilterBar>
    <PeriodSelector presets={["7d", "30d", "90d"]} />
    <DropdownFilter
      label="Region"
      options={regions}
      field="region"
      multiple
      showAll
    />
  </FilterBar>
</FilterProvider>

With Badge

The badge prop accepts any ReactNode and renders it as an accent-colored pill in the header row. Use it for record counts, last-updated timestamps, or status text.

Filters1,204 active accounts

<FilterBar badge={<>1,204 active accounts</>}>
  <PeriodSelector presets={["7d", "30d", "90d"]} />
  <DropdownFilter label="Region" options={regions} field="region" multiple />
</FilterBar>

Sticky Mode

Set sticky to pin the FilterBar to the top of the viewport when scrolling. It applies a frosted-glass backdrop blur with a 12px offset from the top edge.

<FilterBar sticky badge={<>1,204 accounts</>}>
  <FilterBar.Primary>
    <PeriodSelector presets={["30d", "90d", "quarter"]} comparison />
    <DropdownFilter label="Region" options={regions} field="region" multiple />
  </FilterBar.Primary>
</FilterBar>

Sticky mode is best demonstrated in full-page dashboards. See the SaaS demo for a live example.

Collapsible

FilterBar is collapsible by default. Click the header to expand or collapse the filter controls. When collapsed, active filters are shown as compact tags in the header row. Use defaultCollapsed to start in collapsed state, or set collapsible={false} to disable collapse entirely.

Filters

<FilterBar defaultCollapsed>
  <PeriodSelector presets={["7d", "30d", "90d"]} />
  <DropdownFilter label="Region" options={regions} field="region" multiple />
</FilterBar>

Connected (FilterProvider)

FilterBar reads from FilterContext to display active filter tags and counts. Use FilterBar.Primary and FilterBar.Secondaryto split filters into two groups. Secondary filters are hidden behind a "+N more" toggle.

Filters1,204 accounts

useMetricFilters() output

dimensions.region: []

dimensions.plan: []

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

function Dashboard() {
  return (
    <FilterProvider>
      <FilterBar
        tags
        badge={<>1,204 accounts</>}
      >
        <FilterBar.Primary>
          <PeriodSelector presets={["7d", "30d", "90d"]} />
          <DropdownFilter label="Region" options={regions} field="region" multiple showAll />
        </FilterBar.Primary>
        <FilterBar.Secondary>
          <DropdownFilter label="Plan" options={plans} field="plan" multiple showAll />
        </FilterBar.Secondary>
      </FilterBar>
      <MyContent />
    </FilterProvider>
  );
}

function MyContent() {
  const filters = useMetricFilters();
  const regions = filters?.dimensions?.region ?? [];
  return <div>Active regions: {regions.join(", ")}</div>;
}

Props

Prop	Type	Default	Description
`children`*	`React.ReactNode`	—	Filter controls — use FilterBar.Primary and FilterBar.Secondary slots for structured layout.
`tags`	`boolean \| FilterTagsProps`	`true`	Controls FilterTags rendering. true (default): auto-renders FilterTags below filters. false: hides FilterTags. Object: passes through as props to FilterTags (e.g., { exclude: ['_period'], maxVisible: 3 }).
`badge`	`React.ReactNode`	—	Inline right-aligned badge content. Useful for showing result counts, status indicators, etc.
`sticky`	`boolean`	`false`	Stick to viewport top when scrolling. Adds frosted-glass backdrop blur with 12px top offset.
`collapsible`	`boolean`	`false`	Enable accordion behavior — secondary filters collapse/expand with a toggle.
`defaultCollapsed`	`boolean`	`false`	Initial collapsed state when collapsible is true.
`dense`	`boolean`	`false`	Compact mode with reduced padding. Falls back to MetricProvider config.
`className`	`string`	—	Additional CSS class names for the root element.
`classNames`	`{ root?, primary?, secondary?, tags?, badge? }`	—	Sub-element class overrides.
`id`	`string`	—	HTML id attribute.
`data-testid`	`string`	—	Test id for testing frameworks.

Notes

FilterBar must be inside a FilterProvider.
FilterBar.Primary and FilterBar.Secondary are named slot components — they render in the primary and secondary rows respectively.
When collapsible is true, FilterBar.Secondary content hides behind a toggle. FilterBar.Primary always stays visible.
tags={true} (default) auto-renders FilterTags with sensible defaults. Pass an object like { exclude: ['_period'] } to customize.
The badge prop renders inline in the top-right of the filter bar. Great for showing filtered result counts.
Active filter count and clear-all are automatically shown when filters are active.
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.