Filters

FilterBar

A container for dashboard filters with auto FilterTags, badge slot, collapsible accordion, and optional frosted-glass sticky mode. Organise filters into primary and secondary groups with FilterBar.Primary and FilterBar.Secondary.

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.

<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.

<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.

<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.

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`	`ReactNode`	`(required)`	Filter components. Optionally wrap in FilterBar.Primary / FilterBar.Secondary.
`sticky`	`boolean`	`false`	Stick to the top of the viewport with frosted-glass backdrop blur and 12px offset.
`tags`	`boolean \| FilterTagsProps`	`true`	Show active filter tags below the controls. Pass an object to customise FilterTags props.
`badge`	`ReactNode`	`—`	Accent pill in the header row. Use for record counts, status text, etc.
`collapsible`	`boolean`	`true`	Enable expand/collapse accordion on the header click.
`defaultCollapsed`	`boolean`	`false`	Start in collapsed state. Active filters show as compact tags in the header.
`dense`	`boolean`	`false`	Compact mode. Falls back to MetricProvider.
`variant`	`CardVariant`	`—`	Visual variant. Falls back to MetricProvider.
`className`	`string`	`—`	Additional CSS classes on the root element.
`classNames`	`{ root?, controls?, tags?, summary? }`	`—`	Sub-element class overrides.
`id`	`string`	`—`	HTML id.
`data-testid`	`string`	`—`	Test id.

Sub-components

Component	Description
`FilterBar.Primary`	Slot for primary (always-visible) filters. Renders children in a flex-wrap row.
`FilterBar.Secondary`	Slot for secondary filters, hidden behind a "+N more" toggle button.

Notes

FilterBar must be inside a FilterProvider. It reads context to display active filter counts and tags.
Without FilterBar.Primary / FilterBar.Secondary slots, all children render in the primary row.
The collapsed header shows active filters as compact FilterTags. Expand to see full controls.
The "Clear all" button appears automatically when any filters are active. It clears dimensions, period, and cross-filter.
Sticky mode uses backdrop-blur-xl with 80% card-bg opacity for the frosted-glass effect.
Tags are shown by default (tags={true}). Pass false to hide, or a FilterTagsProps object to customise.
Dense mode can be set per-component or inherited from MetricProvider.
FilterBar uses forwardRef and passes through id, data-testid, className, and classNames.