React SegmentedControl: examples and API

Preview

Live preview

Changes apply to this preview only.

board

Width adapts to the available space

"use client";

import { useState } from "react";
import { Badge, Button, SegmentedControl } from "@pimolu/react";

const views = [
  { value: "list", label: "List" },
  { value: "board", label: "Board" },
  { value: "timeline", label: "Timeline" },
];

function ControlledSegmented() {
  const [view, setView] = useState("board");
  return (
    <div className="grid gap-5 min-w-0">
      <div className="flex flex-wrap items-center gap-3 min-w-0">
        <Badge variant="primary">
          {view}
        </Badge>
        <Button
          size="sm"
          appearance="ghost"
          onClick={() => setView(view === "board"
            ? "list"
            : "board")}
        >
          Switch from outside
        </Button>
      </div>
      <SegmentedControl
        aria-label="Controlled view"
        options={views}
        value={view}
        onValueChange={setView}
      />
    </div>
  );
}

export function DemoExample() {
  return (<ControlledSegmented />);
}

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Basic

The first enabled option is selected when no value is given.

Open preview

Sizes

Enumerated from segmentedControlVariantMap: sm, md and lg.

Open preview

Width and orientation

fullWidth stretches the segments; vertical stacks them into a menu.

Open preview

Usage

Keep options short and use a Select when the list becomes long.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluSegmentedControlOption

Type source

PimoluSegmentedControlOption public API
Name	Type	Default	Description
`value`Required	`string`	—	Public Pimolu prop; see the source declaration for details.
`label`Required	`ReactNode`	—	Visible content of the segment.
`disabled`	`boolean \| undefined`	`false`	Public Pimolu prop; see the source declaration for details.

valueRequired: string
No default extracted.
Public Pimolu prop; see the source declaration for details.
labelRequired: ReactNode
No default extracted.
Visible content of the segment.
disabled: boolean | undefined
Default: false
Public Pimolu prop; see the source declaration for details.

PimoluSegmentedControlProps

Type source

PimoluSegmentedControlProps public API
Name	Type	Default	Description
`options`Required	`readonly PimoluSegmentedControlOption[]`	—	Segments, in display order.
`value`	`string \| undefined`	—	Controlled selected value.
`defaultValue`	`string \| undefined`	—	Initial selected value when uncontrolled.
`onValueChange`	`((value: string) => void) \| undefined`	—	Called with the next selected value.
`size`	`"sm" \| "md" \| "lg" \| undefined`	`"md"`	Height and font size. Defaults to "md".
`orientation`	`"horizontal" \| "vertical" \| undefined`	`"horizontal"`	Layout of the segments. Defaults to "horizontal".
`fullWidth`	`boolean \| undefined`	`false`	Stretch the segments across the container.
`disabled`	`boolean \| undefined`	`false`	Disable the whole control.
`name`	`string \| undefined`	—	Name of the hidden input submitted with a form.
`className`	`string \| undefined`	—	Standard React/HTML attribute.
`style`	`CSSProperties \| undefined`	—	Standard React/HTML attribute.
`aria-label`	`string \| undefined`	—	Defines a string value that labels the current element.
`children`	`ReactNode`	—	Standard React/HTML attribute.
`onClick`	`MouseEventHandler<HTMLDivElement> \| undefined`	—	Standard React/HTML attribute.

optionsRequired: readonly PimoluSegmentedControlOption[]
No default extracted.
Segments, in display order.
value: string | undefined
No default extracted.
Controlled selected value.
defaultValue: string | undefined
No default extracted.
Initial selected value when uncontrolled.
onValueChange: ((value: string) => void) | undefined
No default extracted.
Called with the next selected value.
size: "sm" | "md" | "lg" | undefined
Default: "md"
Height and font size. Defaults to "md".
orientation: "horizontal" | "vertical" | undefined
Default: "horizontal"
Layout of the segments. Defaults to "horizontal".
fullWidth: boolean | undefined
Default: false
Stretch the segments across the container.
disabled: boolean | undefined
Default: false
Disable the whole control.
name: string | undefined
No default extracted.
Name of the hidden input submitted with a form.
className: string | undefined
No default extracted.
Standard React/HTML attribute.
style: CSSProperties | undefined
No default extracted.
Standard React/HTML attribute.
aria-label: string | undefined
No default extracted.
Defines a string value that labels the current element.
children: ReactNode
No default extracted.
Standard React/HTML attribute.
onClick: MouseEventHandler<HTMLDivElement> | undefined
No default extracted.
Standard React/HTML attribute.

Accessibility

Name the control and ensure selected state remains clear without color.

Read the accessibility guide →

Related components

Customization Accessibility