Filters

SegmentToggle

A pill-style toggle for switching between segments. Supports single and multi-select, icons, badge counts, color-coded segments, and FilterContext integration.

Use SegmentToggle to let users switch between views, granularities, or filter dimensions. It writes to FilterContext via the field prop, or fires onChange for standalone usage. See the Filtering guide for the full architecture.

Basic Example

<SegmentToggle options={["Daily", "Weekly", "Monthly"]} />

With Icons

Each segment option can include an icon rendered before the label.

<SegmentToggle options={[
  { value: "activity", label: "Activity", icon: <Activity className="h-3.5 w-3.5" /> },
  { value: "trends", label: "Trends", icon: <TrendingUp className="h-3.5 w-3.5" /> },
  { value: "stats", label: "Stats", icon: <BarChart3 className="h-3.5 w-3.5" /> },
]} />

With Badge Counts

Show formatted badge counts on each segment. Numbers pass through the MetricUI format engine.

<SegmentToggle options={[
  { value: "active", label: "Active", badge: 1234 },
  { value: "inactive", label: "Inactive", badge: 56 },
  { value: "archived", label: "Archived", badge: 8 },
]} />

Multi-Select Mode

Enable multiple to allow selecting more than one segment. At least one segment always stays selected.

<SegmentToggle
  options={["Frontend", "Backend", "Mobile", "DevOps"]}
  multiple
  defaultValue={["Frontend", "Backend"]}
/>

Size Variants

Three sizes: sm, md (default), lg.

<SegmentToggle options={["Daily", "Weekly", "Monthly"]} size="sm" />
<SegmentToggle options={["Daily", "Weekly", "Monthly"]} size="md" />
<SegmentToggle options={["Daily", "Weekly", "Monthly"]} size="lg" />

Full Width

Set fullWidth to stretch segments to fill the container.

<SegmentToggle options={["Daily", "Weekly", "Monthly"]} fullWidth />

Vertical Orientation

<SegmentToggle
  options={["Overview", "Details", "Settings"]}
  orientation="vertical"
/>

Color-Coded Segments

Each segment can have its own color accent when active.

<SegmentToggle options={[
  { value: "success", label: "Healthy", color: "#10B981" },
  { value: "warning", label: "Warning", color: "#F59E0B" },
  { value: "error", label: "Critical", color: "#EF4444" },
]} />

Connected (FilterProvider)

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

useMetricFilters() output

dimensions.view: []

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

function Dashboard() {
  return (
    <FilterProvider>
      <SegmentToggle options={["Overview", "Details", "Logs"]} field="view" />
      <MyContent />
    </FilterProvider>
  );
}

function MyContent() {
  const filters = useMetricFilters();
  const view = filters?.dimensions?.view ?? [];
  // Render content based on active segment
  return <div>Active: {view.join(", ")}</div>;
}

Interactive Controls

Experiment with size, multiple, fullWidth, and orientation.

Size

Multiple

Full Width

Orientation

Props

Prop	Type	Default	Description
`options`	`SegmentOption[] \| string[]`	`(required)`	Segment options. Pass string[] as shorthand.
`value`	`string \| string[]`	`—`	Controlled active segment(s).
`defaultValue`	`string \| string[]`	`first option`	Default value for uncontrolled mode.
`onChange`	`(value) => void`	`—`	Change handler. Receives string (single) or string[] (multiple).
`multiple`	`boolean`	`false`	Allow multiple selections.
`field`	`string`	`—`	FilterContext field name. Reads/writes to dimensions.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Layout orientation.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Size variant.
`fullWidth`	`boolean`	`false`	Stretch to fill container.
`dense`	`boolean`	`false`	Compact mode. Falls back to MetricProvider.
`className`	`string`	`—`	Additional CSS classes.
`classNames`	`{ root?, option?, indicator?, badge? }`	`—`	Sub-element class overrides.
`id`	`string`	`—`	HTML id.
`data-testid`	`string`	`—`	Test id.

Notes

SegmentToggle is UI only — it captures the user’s selection and exposes it via context or onChange, but never filters your data.
Without a FilterProvider, SegmentToggle still works via onChange. Context is optional.
In single-select mode, a sliding indicator animates between segments using the unified motion system.
In multi-select mode, at least one segment must always be selected — clicking the last active segment keeps it selected.
Badge counts are formatted through the MetricUI format engine (compact by default).
SegmentToggle uses forwardRef and passes through id, data-testid, className, and classNames.
Dense mode can be set per-component or inherited from MetricProvider.