Segmented Control

A row of buttons for picking one option, with the choice shown as a sliding highlight.

Usage

Code
import { SegmentGroup } from '@leverui/components';
Code
<SegmentGroup.Root>
  <SegmentGroup.Indicator />
  <SegmentGroup.Item>
    <SegmentGroup.ItemText />
    <SegmentGroup.ItemHiddenInput />
  </SegmentGroup.Item>
</SegmentGroup.Root>

Shortcuts

SegmentGroupItems

SegmentGroupItems renders one item for each entry in items. Same output as the loop, when you do not need to customize the items.

Code
<For each={items}>
  {(item) => (
    <SegmentGroup.Item value={item.value}>
      <SegmentGroup.ItemText>{item.label}</SegmentGroup.ItemText>
      <SegmentGroup.ItemHiddenInput />
    </SegmentGroup.Item>
  )}
</For>
Code
<SegmentGroup.Items items={items} />

Examples

Sizes

Use the size prop to change the size of the segmented control.

size = xs

size = sm

size = md

size = lg

Controlled

Use the value and onValueChange props to control the selected item.

Hook Form

Here's an example of how to use the SegmentGroup in a form with a Solid signal holding its value.

Vertical

By default, the segmented control is horizontal. Set the orientation prop to vertical to change the orientation of the segmented control.

Disabled

Use the disabled prop to disable the segmented control.

Disabled Item

Use the disabled prop on the item to disable it.

Custom Indicator

Customize the indicator appearance using CSS variables like --leverui-segment-group-indicator-background and --leverui-segment-group-indicator-shadow.

Color Palette

By default, the segment control doesn't change its design based on a color palette. This example shows how to customize the segmented control with CSS to use one.

Icon

Render the label as a JSX.Element to render an icon.

Card

Here's an example of how to use the SegmentGroup within a Card.

Search homes for rent

Guides

Built on standard radio inputs, so keyboard and form submission work as they do for radio buttons. Name every group with aria-label or aria-labelledby.

Items takes strings, or objects with a value, a label, and an optional disabled flag. label can be JSX. Each option renders an Item, an ItemText, and an ItemHiddenInput. Put those parts together yourself when an option needs more content. Indicator draws the background that slides to the selected option. Place it inside Root.

When items changes, the group keeps its selection if that value is still in the list. An item with the same value keeps its radio element, so the indicator stays lined up.

Use as="div" on Items or Item when the container should not be a label. With asChild, the container Item renders must not be interactive and must not be another label. A div is fine.

RootProvider takes a state machine from useSegmentGroup. PropsProvider gives Root reactive default props without replacing the group. A responsive value, such as size={{ base: 'xs', md: 'lg' }}, switches at the 768px breakpoint through CSS media queries. For right-to-left layouts, wrap the group in LocaleProvider. The arrow keys follow its direction.

required on Root uses the browser's radio group validation: the form is invalid until someone picks an option. invalid marks the group and its radio inputs as invalid. A disabled group is left out of the form data. A read-only group shows its value, but its inputs are disabled, so it is not submitted.

Props

Root

PropDefaultTypeDescription
orientationhorizontal'horizontal' | 'vertical'Lay the options out in a row or a column.
sizemd'xs' | 'sm' | 'md' | 'lg' or responsive mapControl size.
asdivNative HTML tagHTML tag to render.
asChild—Solid render functionRender your own element with the root's props.
unstyledfalsebooleanTurn off the Lever UI styles.
defaultValue—stringOption selected at first. Uncontrolled.
disabled—booleanDisable the whole group.
form—stringForm the underlying inputs belong to.
id—stringUnique id of the group's state machine.
ids—Partial<ElementIds>Ids of the group's elements. For composing the parts yourself.
invalid—booleanMark the group as invalid.
name—stringName of the inputs. Used on form submit.
onValueChange—(details: ValueChangeDetails) => voidCalled when someone selects an option.
readOnly—booleanMake the group read-only.
required—booleanMark the group as required.
value—stringSelected option. Controlled.

Customize with CSS

Import the library CSS once. Customize with class and style, the .leverui-segment-group__* part classes, and public variables such as --leverui-segment-group-background, --leverui-segment-group-indicator-background, --leverui-segment-group-indicator-shadow, --leverui-segment-group-item-height, --leverui-segment-group-item-line-height, and --leverui-segment-group-radius. Plain CSS that is not inside a cascade layer overrides the defaults.