SegmentedControl

Segmented toggle control for selecting one option from a small set. Rendered as a radio group (`role="radiogroup"`), so reach for it when picking a value — filters, settings, or view modes whose content you render yourself. If selecting an option should show or hide associated content panels, use Tabs instead.

Examples

Default

DayWeekMonth

<SegmentedControl label="Date range" layout="hug" size="md" value="day" />

Sizes

DayWeekMonth

DayWeekMonth

DayWeekMonth

function SizesStory(args: SegmentedControlProps): React.JSX.Element {
  const [value, setValue] = useState(args.value);

  return (
    <div style={{display: 'grid', gap: 16, justifyItems: 'start'}}>
      <SegmentedControl {...args} onChange={setValue} size="sm" value={value}>
        <SegmentedControlItem label="Day" value="day" />
        <SegmentedControlItem label="Week" value="week" />
        <SegmentedControlItem label="Month" value="month" />
      </SegmentedControl>
      <SegmentedControl {...args} onChange={setValue} size="md" value={value}>
        <SegmentedControlItem label="Day" value="day" />
        <SegmentedControlItem label="Week" value="week" />
        <SegmentedControlItem label="Month" value="month" />
      </SegmentedControl>
      <SegmentedControl {...args} onChange={setValue} size="lg" value={value}>
        <SegmentedControlItem label="Day" value="day" />
        <SegmentedControlItem label="Week" value="week" />
        <SegmentedControlItem label="Month" value="month" />
      </SegmentedControl>
    </div>
  );
}

<SizesStory {...args} />

Fill Layout

OverviewActivitySettings

function FillLayoutStory(args: SegmentedControlProps): React.JSX.Element {
  const [value, setValue] = useState(args.value);

  return (
    <div style={{maxWidth: 480}}>
      <SegmentedControl
        {...args}
        layout="fill"
        onChange={setValue}
        value={value}>
        <SegmentedControlItem label="Overview" value="overview" />
        <SegmentedControlItem label="Activity" value="activity" />
        <SegmentedControlItem label="Settings" value="settings" />
      </SegmentedControl>
    </div>
  );
}

<FillLayoutStory {...args} />

Disabled

DayWeekMonth

<SegmentedControl
  label="Date range"
  layout="hug"
  size="md"
  value="day"
  isDisabled
/>

Disabled Item

DayWeekMonth

function DisabledItemStory(args: SegmentedControlProps): React.JSX.Element {
  const [value, setValue] = useState(args.value);

  return (
    <SegmentedControl {...args} onChange={setValue} value={value}>
      <SegmentedControlItem label="Day" value="day" />
      <SegmentedControlItem isDisabled label="Week" value="week" />
      <SegmentedControlItem label="Month" value="month" />
    </SegmentedControl>
  );
}

<DisabledItemStory {...args} />

Empty Selection

DayWeekMonth

function EmptySelectionStory(args: SegmentedControlProps): React.JSX.Element {
  const [value, setValue] = useState<string>();

  return (
    <SegmentedControl {...args} onChange={setValue} value={value}>
      <SegmentedControlItem isDisabled label="Day" value="day" />
      <SegmentedControlItem label="Week" value="week" />
      <SegmentedControlItem label="Month" value="month" />
    </SegmentedControl>
  );
}

<EmptySelectionStory {...args} />

Icon Only

HomeNotificationsSettings

function IconOnlyStory(args: SegmentedControlProps): React.JSX.Element {
  const [value, setValue] = useState(args.value);

  return (
    <SegmentedControl {...args} onChange={setValue} value={value}>
      <SegmentedControlItem
        icon={Home}
        isLabelHidden
        label="Home"
        value="home"
      />
      <SegmentedControlItem
        icon={Bell}
        isLabelHidden
        label="Notifications"
        value="notifications"
      />
      <SegmentedControlItem
        icon={Settings}
        isLabelHidden
        label="Settings"
        value="settings"
      />
    </SegmentedControl>
  );
}

<IconOnlyStory {...args} />

Icon With Label

CalendarListTeam

function IconWithLabelStory(args: SegmentedControlProps): React.JSX.Element {
  const [value, setValue] = useState(args.value);

  return (
    <SegmentedControl {...args} onChange={setValue} value={value}>
      <SegmentedControlItem icon={Calendar} label="Calendar" value="calendar" />
      <SegmentedControlItem icon={List} label="List" value="list" />
      <SegmentedControlItem icon={Users} label="Team" value="team" />
    </SegmentedControl>
  );
}

<IconWithLabelStory {...args} />

Many Items

OverviewActivityMembersFilesBillingSecurity

function ManyItemsStory(args: SegmentedControlProps): React.JSX.Element {
  const [value, setValue] = useState(args.value);

  return (
    <SegmentedControl {...args} onChange={setValue} value={value}>
      <SegmentedControlItem label="Overview" value="overview" />
      <SegmentedControlItem label="Activity" value="activity" />
      <SegmentedControlItem label="Members" value="members" />
      <SegmentedControlItem label="Files" value="files" />
      <SegmentedControlItem label="Billing" value="billing" />
      <SegmentedControlItem label="Security" value="security" />
    </SegmentedControl>
  );
}

<ManyItemsStory {...args} />

Read Only

DayWeekMonth

<SegmentedControl
  label="Date range"
  layout="hug"
  size="md"
  value="day"
  isReadOnly
/>

API

SegmentedControl

Segmented toggle control for selecting one option from a small set. Rendered as a radio group (`role="radiogroup"`), so reach for it when picking a value — filters, settings, or view modes whose content you render yourself. If selecting an option should show or hide associated content panels, use Tabs instead.

Prop	Type	Default	Description
children*	ReactNode	—	SegmentedControlItem children.
className	string	—	Additional CSS class names applied to the root element.
data-testid	string	—	Test ID applied to the root element.
isDisabled	boolean	false	Whether the entire control is disabled.
isReadOnly	boolean	false	Whether the selected segment is displayed without allowing interaction.
label*	string	—	Accessible label for the radio group.
layout	"fill" | "hug"	'hug'	Segment layout mode.
onChange*	(value: TValue) => void	—	Called when a segment is selected.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the root element.
size	"sm" | "md" | "lg"	'md'	Control size.
style	CSSProperties	—	Inline styles applied to the root element.
value	TValue	—	Current selected value, or undefined when no segment is selected.

SegmentedControlItem

Individual segment within a `SegmentedControl`.

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the segment.
data-testid	string	—	Test ID applied to the segment.
icon	IconComponent	—	Icon element displayed before the label.
isDisabled	boolean	false	Whether this segment is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Accessible and visible label for the segment.
ref	Ref<HTMLButtonElement>	—	Ref forwarded to the segment button.
style	CSSProperties	—	Inline styles applied to the segment.
value*	TValue	—	Unique value represented by this segment.