SegmentToggle

A pill-style toggle for switching between segments with single/multi-select, icons, badges, and FilterContext integration.

import { SegmentToggle } from "metricui";

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[]`	—	Segment options. Pass string[] as shorthand — each string becomes { value: str, label: str }.
`value`	`string \| string[]`	—	Controlled active segment(s).
`defaultValue`	`string \| string[]`	`first option`	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. At least one must always remain selected.
`field`	`string`	—	FilterContext field name. When set, reads/writes to FilterContext dimensions.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Layout orientation.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Size variant.
`fullWidth`	`boolean`	`false`	Stretch segments to fill container.
`dense`	`boolean`	`false`	Compact mode. Falls back to MetricProvider config.
`className`	`string`	—	Additional CSS class names for the root element.
`classNames`	`{ root?, option?, indicator?, badge? }`	—	Sub-element class overrides.
`id`	`string`	—	HTML id attribute.
`data-testid`	`string`	—	Test id for testing frameworks.

Data Shape

interface SegmentOption {
  value: string;       // Unique value
  label?: string;      // Display label (defaults to value)
  icon?: ReactNode;    // Icon before label
  badge?: number;      // Badge count (formatted via format engine)
  badgeFormat?: FormatOption;  // Badge format option
  color?: string;      // Active accent color
}

Notes

SegmentToggle 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.
In single-select mode, a sliding indicator animates between segments using the motion system.
In multi-select mode, at least one segment must always remain selected.
Badge counts are formatted through the format engine (compact by default).
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.