SegmentedControl

Import

import { SegmentedControl } from '@envsemble/envui';

Usage

<SegmentedControl
  aria-label="Work items"
  value={status}
  onValueChange={setStatus}
  items={[
    { value: 'open', label: 'Open', count: 12 },
    { value: 'done', label: 'Done', count: 4 },
  ]}
/>

Leave it uncontrolled, starting at defaultValue, the first item by default, or control it with value and onValueChange. items are two to five SegmentedControlItems in the order they show, each with its value, a short label, and optionally a count, read as part of its name, a decorative icon and disabled. aria-label names the control, which has no visible label; disabled turns off the whole control.

Size and width

size is sm, md or lg; without it the control takes its container's, md unless the container sets another. Without fullWidth it is as wide as its items and scrolls in a container too narrow for them; with fullWidth it fills the width, split evenly, and a label too long for its share shows whole in a tooltip, or wraps on touch screens.

Composition

The track, env-segmented-control, carries data-size and data-full-width; each segment, env-segmented-control-item, data-checked while chosen, when it is the thumb, and data-disabled.

Accessibility

You provide

An aria-label that names what the control switches.
The content that follows the choice.

envUI provides

A radiogroup with each segment a radio, one tab stop and the arrow keys.
Each option named by its label and count, such as Open 12.
The whole label as the name when fullWidth cuts it short.

Props

One choice among a few items, such as views or filters of the same content: segments in a recessed track, the chosen one raised on a thumb. A radio group, with one tab stop and arrow keys.

Prop	Type	Description
`items`required	`readonly SegmentedControlItem[]`	The items, two to five, in the order they show.
`value`	`string`	The chosen item's value, for a control the application keeps; update it from onValueChange.
`defaultValue`Default `the first item's value`	`string`	The item an uncontrolled control starts with chosen.
`onValueChange`	`(value: string) => void`	Receives the value of the item people choose, by pressing it or with the arrow keys.
`aria-label`required	`string`	The group's accessible name, such as Work items; the control has no visible label.
`size`	`'sm''md''lg'`	The height, as on every control: sm, md or lg in the current scale, so it lines up with buttons and fields of the same size. Without it, it takes the control height of its container, md unless the container sets another.
`fullWidth`Default `false`	`boolean`	Fill the available width, split evenly between the items; a label too long for its share is cut short with an ellipsis and shows whole in a tooltip. Without it the control is as wide as its items, and scrolls in a container too narrow for them.
`disabled`Default `false`	`boolean`	Disable every item; the control can't be focused or changed.

Also accepts the native props of <div>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-segmented-control: The segmented control: the track the segments sit in.
env-segmented-control-item: One segment; the chosen one rises on a raised thumb.
env-segmented-control-item-count: A segment's count.
env-segmented-control-item-label: A segment's label.
env-segmented-control-thumb: The raised thumb that travels to the chosen segment, hidden until it has measured it.
data-checked: Any value, or present on env-segmented-control-item
data-disabled: Any value, or present on env-segmented-control-item
data-full-width: Present
data-placed: Any value, or present on env-segmented-control-thumb
data-size: lg · md · sm

Color properties

Each sets a color of one instance, through style or CSS; its hover, focus and press follow it. They are public and versioned.

--env-segmented-control-container: The track behind the options, the neutral fill by default.
--env-segmented-control-outline: An outline around the track, none by default.
--env-segmented-control-content: The labels of the options not chosen, and the color of their state layers.
--env-segmented-control-selected: The chosen option's thumb; set, it takes state layers instead of the designed hover and press fills.
--env-segmented-control-selected-content: The chosen option's label.

Changelog

1.0.0: options is items, and SegmentedControlOption is SegmentedControlItem. The segments' classes are env-segmented-control-item, -item-label and -item-count. An unchosen segment's count keeps 4.5:1 contrast. SegmentedControl takes ref, style, id and other attributes of its rail, and its page is under Forms & selection.
1.0.0-prerelease.6: Colors under the pointer and while pressed change with --env-motion-ease-enter, rather than easing in slowly, so hover and press show from the first frame.

One thumb, env-segmented-control-thumb, travels to the chosen segment rather than two segments cross-fading; under reduced motion the fill still fades across.

Under the pointer a segment not chosen takes no layer, only the text color on its label, and pressed only the faint neutral pressed layer, so only the thumb reads as chosen, in dark too, where the thumb is the raised neutral grade, --env-color-bg-neutral-strong-hover, opaque and clearly lighter than a hovered segment; at high contrast it keeps a layer of the neutral fill.

SegmentedControl is segments in a recessed track, the chosen one raised on a thumb with a soft shadow, rather than Material's connected outlined segments: no outline, no lines between the segments and no check, and a chosen segment shows its icon. Tabs keep their indicator under the selected tab, so the two still read differently. The check, env-segmented-control-item-indicator, is gone. --env-segmented-control-container sets the track, the neutral fill by default, --env-segmented-control-outline an outline around it, none by default, and --env-segmented-control-selected the thumb.
1.0.0-prerelease.5: It can be uncontrolled, with defaultValue.
1.0.0-prerelease.2: SegmentedControl looks like Material's segmented buttons: connected segments in one outline, the chosen one in the selected fill, --env-color-bg-selected, with a check, env-segmented-control-item-check, in place of its icon, so it reads differently from Tabs. --env-segmented-control-outline sets the outline. The API stays.