FormsGenerated from the public API

SegmentedControl

A compact exclusive choice that reads as a single control.

@luc/ui

Examples

One value, three options

A single value with a sliding indicator: this is not a `ToggleGroup`, which is a set of independent options.

<SegmentedControl value={range} onValueChange={setRange} aria-label="Range">
  <SegmentedItem value="1m">1M</SegmentedItem>
  <SegmentedItem value="3m">3M</SegmentedItem>
  <SegmentedItem value="1y">1Y</SegmentedItem>
</SegmentedControl>

Sizes and fill

`sm` for a toolbar or a topbar; `fill` makes the track take the width it is given, which is what a panel header wants.

<SegmentedControl defaultValue="1d" size="sm">…</SegmentedControl>
<SegmentedControl defaultValue="price" fill>…</SegmentedControl>

Icons beside text

`leadingIcon` is decoration and the item's own text is the name; an item with only an icon needs its own `aria-label`.

<SegmentedControl defaultValue="chart" aria-label="View">
  <SegmentedItem value="chart" leadingIcon={<RiLineChartLine />}>Chart</SegmentedItem>
  <SegmentedItem value="table" leadingIcon={<RiTableLine />}>Table</SegmentedItem>
</SegmentedControl>

A disabled item

One unavailable option does not disable the choice: the item is skipped by the arrow keys and can never take the value.

<SegmentedControl defaultValue="3m" aria-label="Range">
  <SegmentedItem value="1m">1M</SegmentedItem>
  <SegmentedItem value="3m">3M</SegmentedItem>
  <SegmentedItem value="max" disabled>MAX</SegmentedItem>
</SegmentedControl>

Usage

import { SegmentedControl, SegmentedItem } from "@luc/ui";

<SegmentedControl defaultValue="3m" aria-label="Range">
  <SegmentedItem value="1m">1M</SegmentedItem>
  <SegmentedItem value="3m">3M</SegmentedItem>
</SegmentedControl>

Package setup — peer requirements, the stylesheet and the provider — is on installation.

API

Read from the published TypeScript API, so a prop that is not listed here does not exist and a default that is listed is the one the compiler sees.

Exported symbols
Export	Kind	Signature
`SegmentedControl`	11 documented props	`({ className, size, fill, value, defaultValue, onValueChange, ref, children, ...props }: SegmentedControlProps) => import("@types/react").JSX.Element`
`SegmentedItem`	4 documented props	`({ className, children, leadingIcon, value, size, ...props }: SegmentedItemProps) => import("@types/react").JSX.Element`

SegmentedControl props

Type: SegmentedControlProps

Values the compiler reads from the declaration.

SegmentedControl props
Prop	Type	Default	Notes
`asChild?`inherited	`boolean \| undefined`	`—`
`defaultValue?`inherited	`string \| undefined`	`—`	The value of the item that is pressed when initially rendered. Use `defaultValue` if you do not need to control the state of a toggle group.
`dir?`inherited	`Direction \| undefined`	`—`
`disabled?`inherited	`boolean \| undefined`	`—`	Whether the group is disabled from user interaction.
`fill?`	`boolean \| undefined`	`—`
`loop?`inherited	`boolean \| undefined`	`—`
`onValueChange?`inherited	`((value: string) => void) \| undefined`	`—`	The callback that fires when the value of the toggle group changes.
`orientation?`inherited	`"horizontal" \| "vertical" \| undefined`	`—`
`ref?`	`Ref<HTMLDivElement> \| undefined`	`—`
`size?`	`"sm" \| "md" \| undefined`	`—`	Match the item size. `sm` is for toolbars and topbars.
`value?`inherited	`string \| undefined`	`—`	The controlled stateful value of the item that is pressed.

SegmentedItem props

Type: SegmentedItemProps

Values the compiler reads from the declaration.

SegmentedItem props
Prop	Type	Default	Notes
`asChild?`inherited	`boolean \| undefined`	`—`
`leadingIcon?`	`ReactNode`	`—`
`size?`	`"sm" \| "md" \| undefined`	`—`
`value`inherited	`string`	`—`	A string value for the toggle group item. All items within a toggle group should use a unique value.

Guidelines

Use it for one value with two to five short options that should all stay visible.
Reach for `fill` inside a panel header, and `sm` in a toolbar or a topbar.
Put the item's meaning in its text; `leadingIcon` is decoration beside it.

Don't

Use a segmented control for independent options — that is `ToggleGroup`, and the sliding indicator would lie about the state.
Use it as navigation: it selects a value, it does not go somewhere.
Disable the whole control for one unavailable option; disable the item.

Accessibility

The control is a single-value composite: one tab stop, arrow keys between the items, and the selected item is the only one reported as selected. A disabled item is skipped by the arrow keys and can never take the value.

Family

Forms

Inputs, their validation surfaces and the form lifecycle around them.

24 documented entries in this family. Open the family index