The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: SegmentedControl
description: Choose one value from a compact group of labeled or icon options.
---
import { PageBanner } from "/snippets/page-banner.mdx"
import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import SegmentedControlReference from '/snippets/ui/generated/components/input/segmented-control.mdx';
## Overview
`SegmentedControl` is a preset assembled from [Radio](/ui/primitives/input/radio) and [RadioGroup](/ui/primitives/input/radio-group), with joined options. Use it for a short, mutually exclusive choice. For navigation between content panels, use [Tabs](/ui/primitives/navigation/tabs).
<StoryEmbed
storyId="components-input-segmentedcontrol--display"
title="SegmentedControl example"
height={110}
/>
## Usage
Supply an accessible group name with `aria-label` or `aria-labelledby`. Each option needs a unique string `value`. Selection belongs to the group; options do not have independent checked state.
```tsx
import { SegmentedControl } from 'twenty-ui/components/input';
export const BillingPeriod = () => (
<SegmentedControl
aria-label="Billing period"
name="billingPeriod"
defaultValue="annual"
options={[
{ label: 'Annual', value: 'annual' },
{ label: 'Monthly', value: 'monthly' },
]}
/>
);
```
`defaultValue` initializes selection. The group owns later changes. Add `onValueChange` if you need to observe them without controlling the value.
## Controlled state
```tsx
import { useState } from 'react';
import { SegmentedControl } from 'twenty-ui/components/input';
export const BillingPeriod = () => {
const [period, setPeriod] = useState('annual');
return (
<SegmentedControl
aria-label="Billing period"
name="billingPeriod"
value={period}
onValueChange={setPeriod}
options={[
{ label: 'Annual', value: 'annual' },
{ label: 'Monthly', value: 'monthly' },
]}
/>
);
};
```
Keep `value` in application state and update it in `onValueChange`. Do not combine `value` and `defaultValue` or switch ownership modes after mounting.
## Icon options
```tsx
import { SegmentedControl } from 'twenty-ui/components/input';
import { IconList, IconLayoutKanban } from 'twenty-ui/icon';
export const RecordLayout = () => (
<SegmentedControl
aria-label="Record layout"
defaultValue="list"
itemWidth="content"
options={[
{ value: 'list', startIcon: <IconList />, 'aria-label': 'List' },
{
value: 'kanban',
startIcon: <IconLayoutKanban />,
'aria-label': 'Kanban',
},
]}
/>
);
```
An icon-only option requires an `aria-label`. `startIcon` is decorative and hidden from assistive technology. Options with visible text use `label` and may also provide `startIcon`. Set `disabled` on an option to prevent its selection, or on the group to disable every option.
## Keyboard, forms, and direction
Tab enters the group; arrow keys move between enabled options and update selection. This follows radio behavior. Dropdown selection groups move focus with arrow keys and select on activation. `itemWidth="equal"` is the default; use `content` when labels should determine widths. Set `name` to include the selected value in native form submission. The preset preserves RadioGroup's `required`, `readOnly`, disabled state, and native form integration. `onValueChange` receives the selected value and Base UI event details, including `reason` and `cancel()`.
For right-to-left content, pair [DirectionProvider](/ui/primitives/layout/direction-provider) with a matching `dir` attribute. The provider controls directional interaction; `dir` controls the document layout.
## Composition and native props
Native props, `className`, `style`, `render`, and `ref` target the group's `div`. Use `render` to compose that group with another element; preserve its accessible name and radio-group semantics. Options render `span` elements with `role="radio"` and hidden native radio inputs. The preset does not assign tab or tab-panel roles. For custom radio content, per-option native props, or a different radio render target, compose `Radio.Root` and `RadioGroup` directly.
## Props
<SegmentedControlReference />
<PageBanner illustration="page-cover-switch" />