Skip to content

The open alternative to Salesforce, designed for AI.

4.2 KB
Raw Blame
---
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" />