InputsReact

Segment Group

One choice out of a few, drawn as a bar of segments with a pill under the chosen one.

Rendered by React 19.3.1

Loading React…

import { SegmentGroup } from '@hamur/react/segment-group'

const views = [
  { value: 'day', label: 'Day' },
  { value: 'week', label: 'Week' },
  { value: 'month', label: 'Month' },
]

export default function SegmentGroupExample() {
  return (
    <div>
      <h3 id="segment-group-view" className="segment-group-heading">
        View
      </h3>
      <SegmentGroup.Root
        className="segment-group"
        aria-labelledby="segment-group-view"
        defaultValue="week"
      >
        <SegmentGroup.Indicator className="segment-group-indicator" />
        {views.map((view) => (
          <SegmentGroup.Item
            key={view.value}
            className="segment-group-item"
            value={view.value}
          >
            {view.label}
          </SegmentGroup.Item>
        ))}
      </SegmentGroup.Root>
    </div>
  )
}

Not measured yetTests passing in React

Not measured yetSize

Not measured yetMemory

Not measured yetSpeed

[N] commits

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<SegmentGroup.Root>
  <SegmentGroup.Indicator />
  <SegmentGroup.Item />
</SegmentGroup.Root>

Examples

Vertical

A row density choice stacked in a column; the pill moves on the block axis.

SegmentGroupVertical.tsx

import { SegmentGroup } from '@hamur/react/segment-group'

const densities = [
  { value: 'compact', label: 'Compact' },
  { value: 'comfortable', label: 'Comfortable' },
  { value: 'spacious', label: 'Spacious' },
]

export default function SegmentGroupVerticalExample() {
  return (
    <SegmentGroup.Root
      className="segment-group"
      aria-label="Row density"
      orientation="vertical"
      defaultValue="comfortable"
    >
      <SegmentGroup.Indicator className="segment-group-indicator" />
      {densities.map((density) => (
        <SegmentGroup.Item key={density.value} className="segment-group-item" value={density.value}>
          {density.label}
        </SegmentGroup.Item>
      ))}
    </SegmentGroup.Root>
  )
}

Disabled

A billing period whose third segment is disabled; the arrow keys skip it.

SegmentGroupDisabled.tsx

import { SegmentGroup } from '@hamur/react/segment-group'

export default function SegmentGroupDisabledExample() {
  return (
    <div className="stack">
      <SegmentGroup.Root className="segment-group" aria-label="Billing" defaultValue="monthly">
        <SegmentGroup.Indicator className="segment-group-indicator" />
        <SegmentGroup.Item className="segment-group-item" value="monthly">
          Monthly
        </SegmentGroup.Item>
        <SegmentGroup.Item className="segment-group-item" value="yearly">
          Yearly
        </SegmentGroup.Item>
        <SegmentGroup.Item className="segment-group-item" value="lifetime" disabled>
          Lifetime
        </SegmentGroup.Item>
      </SegmentGroup.Root>
      <p className="muted">Lifetime is sold out.</p>
    </div>
  )
}

Controlled

Icon-only alignment segments named by aria-label, with the value held by the app and a Reset button.

SegmentGroupControlled.tsx

import * as React from 'react'
import { SegmentGroup } from '@hamur/react/segment-group'

type Align = 'left' | 'center' | 'right'

const alignments: { value: Align; label: string; lines: string[] }[] = [
  { value: 'left', label: 'Align left', lines: ['M4 6h16', 'M4 12h10', 'M4 18h14'] },
  { value: 'center', label: 'Align center', lines: ['M4 6h16', 'M7 12h10', 'M5 18h14'] },
  { value: 'right', label: 'Align right', lines: ['M4 6h16', 'M10 12h10', 'M6 18h14'] },
]

export default function SegmentGroupControlledExample() {
  const [align, setAlign] = React.useState<Align>('left')
  return (
    <div className="stack">
      <div className="row">
        <SegmentGroup.Root
          className="segment-group"
          aria-label="Text alignment"
          value={align}
          onValueChange={setAlign}
        >
          <SegmentGroup.Indicator className="segment-group-indicator" />
          {alignments.map((alignment) => (
            <SegmentGroup.Item
              key={alignment.value}
              className="segment-group-item segment-group-icon"
              value={alignment.value}
              aria-label={alignment.label}
            >
              <svg width="16" height="16" viewBox="0 0 24 24" aria-hidden="true">
                {alignment.lines.map((d) => (
                  <path key={d} d={d} />
                ))}
              </svg>
            </SegmentGroup.Item>
          ))}
        </SegmentGroup.Root>
        <button
          type="button"
          className="button segment-group-reset"
          onClick={() => setAlign('left')}
        >
          Reset
        </button>
      </div>
      <p className="segment-group-preview" style={{ textAlign: align }}>
        The quick brown fox jumps over the lazy dog.
      </p>
      <p className="muted segment-group-value">Alignment: {align}</p>
    </div>
  )
}

Form

In a Field labelled "Default view", submitted with its form and brought back to Week by a reset.

SegmentGroupForm.tsx

import * as React from 'react'
import { Field } from '@hamur/react/field'
import { Form } from '@hamur/react/form'
import { SegmentGroup } from '@hamur/react/segment-group'

const views = [
  { value: 'day', label: 'Day' },
  { value: 'week', label: 'Week' },
  { value: 'month', label: 'Month' },
]

export default function SegmentGroupFormExample() {
  const [submitted, setSubmitted] = React.useState('')
  return (
    <Form
      className="stack"
      onFormSubmit={(_values, details) => {
        const form = details.event.target as HTMLFormElement
        setSubmitted([...new FormData(form)].map(([key, value]) => `${key}=${value}`).join('&'))
      }}
    >
      <Field.Root name="view" className="field">
        <Field.Label className="segment-group-label" nativeLabel={false} render={<div />}>
          Default view
        </Field.Label>
        <SegmentGroup.Root className="segment-group" defaultValue="week">
          <SegmentGroup.Indicator className="segment-group-indicator" />
          {views.map((view) => (
            <SegmentGroup.Item key={view.value} className="segment-group-item" value={view.value}>
              {view.label}
            </SegmentGroup.Item>
          ))}
        </SegmentGroup.Root>
      </Field.Root>
      <div className="row">
        <button className="button" type="submit">
          Save
        </button>
        <button className="button" type="reset" onClick={() => setSubmitted('')}>
          Reset
        </button>
      </div>
      {submitted ? <pre className="output">{submitted}</pre> : null}
    </Form>
  )
}

API reference

17 props across 3 parts, in React syntax. className, style, render are listed once, under Shared props.

Indicator`SegmentGroup.Indicator`

A visual indicator that can be styled to match the position of the checked segment. Renders a <span>.

Indicator props
Prop	Type	Default
`renderBeforeHydration`Whether to render itself before React hydrates.	`boolean`	`false`

Indicator data attributes
Data attribute	Description
`data-orientation`	Indicates the layout direction of the segments.
`data-activation-direction`	Indicates the direction of the last move (based on the previously checked segment).
`data-resizing`	Present from a re-measure that is not a change of value (a resize) until the next animation frame, so a transition can be turned off while it is present.

Indicator CSS variables
CSS variable	Description
`--active-segment-left`	The distance from the left edge of the Root's padding box to the checked segment.
`--active-segment-right`	The distance from the checked segment to the right edge of the Root's padding box.
`--active-segment-top`	The distance from the top edge of the Root's padding box to the checked segment.
`--active-segment-bottom`	The distance from the checked segment to the bottom edge of the Root's padding box.
`--active-segment-width`	The width of the checked segment.
`--active-segment-height`	The height of the checked segment.

Item`SegmentGroup.Item`

A segment of the group: a radio with its text as its name. and a hidden <input> beside. Renders a <span>.

Item props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`false`
`value`requiredThe unique identifying value of the segment in the group.	`TValue`	`—`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`readOnly`Whether the user should be unable to check the segment.	`boolean`	`false`
`required`Whether the user must choose a value before submitting a form.	`boolean`	`false`
`inputRef`A ref to access the hidden input element.	`React.Ref<HTMLInputElement>`	`—`

Item data attributes
Data attribute	Description
`data-orientation`	Indicates the layout direction of the segments.
`data-checked`	Present when the segment is checked.
`data-unchecked`	Present when the segment is not checked.
`data-disabled`	Present when the segment is disabled.
`data-readonly`	Present when the segment is readonly.
`data-required`	Present when the segment is required.
`data-valid`	Present when the segment is in a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the segment is in an invalid state (when wrapped in Field.Root).
`data-touched`	Present when the segment has been touched (when wrapped in Field.Root).
`data-dirty`	Present when the segment's value has changed (when wrapped in Field.Root).
`data-filled`	Present when the segment is checked (when wrapped in Field.Root).
`data-focused`	Present when the segment is focused (when wrapped in Field.Root).

Root`SegmentGroup.Root`

Groups the segments of a single-choice bar and measures the checked one for the Indicator. Renders a <div>.

Root props
Prop	Type	Default
`value`The controlled value of the checked segment, or `null` for none.	`TValue \| null`	`—`
`defaultValue`The uncontrolled value of the segment checked when the component is initially rendered, and	`TValue \| null`	`—`
`onValueChange`Callback fired when the value changes.	`((value: TValue, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element \| undefined; }) => void)`	`—`
`orientation`The layout direction of the segments.	`SegmentGroupOrientation`	`'horizontal'`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`readOnly`Whether the user should be unable to check a different segment.	`boolean`	`false`
`required`Whether the user must choose a value before submitting a form.	`boolean`	`false`
`name`Identifies the field when a form is submitted.	`string`	`—`
`form`Identifies the form that owns the hidden inputs.	`string`	`—`
`inputRef`A ref to access the hidden input element.	`React.Ref<HTMLInputElement>`	`—`

Root data attributes
Data attribute	Description
`data-orientation`	Indicates the layout direction of the segments.
`data-disabled`	Present when the segment group is disabled.
`data-valid`	Present when the segment group is in a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the segment group is in an invalid state (when wrapped in Field.Root).
`data-touched`	Present when the segment group has been touched (when wrapped in Field.Root).
`data-dirty`	Present when the segment group's value has changed (when wrapped in Field.Root).
`data-filled`	Present when a segment is checked (when wrapped in Field.Root).
`data-focused`	Present when a segment is focused (when wrapped in Field.Root).

Shared props

Every part that renders an element takes these.

Shared props
Prop	Type
`className`CSS class applied to the element, or a function that returns a class based on the component's state.	`string \| ((state: State) => string \| undefined)`
`style`Style applied to the element, or a function that returns a style object based on the component's state.	`React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined)`
`render`Allows you to replace the component's HTML element with a different tag, or compose it with another component.	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, State>`

Keyboard and accessibility

Keyboard

Keyboard
Keys	Does	Part
`ArrowLeftArrowRightArrowUpArrowDown`	Moves to the previous or next segment and checks it, wrapping at the ends, in either layout	Item
`ArrowRight`	Skips a disabled segment	Item
`Space`	Checks the focused segment	Item
`Enter`	Changes nothing and submits nothing	Item
`HomeEnd`	Change nothing	Item
`Tab`	Enters the group on the checked segment, then leaves it in one step	Root

Accessibility

What the parts set
Part	Sets	So that
Root	`role="radiogroup"` and `aria-orientation`, named by the Field label, a Fieldset legend, or the app's `aria-labelledby` or `aria-label`	the segments are said as one set, with its question
Root	`aria-disabled`, `aria-readonly`, `aria-required` from `disabled`, `readOnly` and `required`	the group's constraints are said
Item	`role="radio"` with `aria-checked`, the roving `tabindex`, and a hidden radio input beside it	each segment is said as a choice with its state, and submits a value
Item	its text as its name; an icon-only `Item` takes the app's `aria-label`	every segment has a name
Indicator	`role="presentation"`, no text, never focused; `hidden` until measured	the pill is drawing only, and nothing jumps on the first paint

Focus order

The group is one tab stop: the checked segment, or the first enabled one while none is checked.
The arrow keys move focus and the choice together; disabled segments are skipped.
Tab leaves the group in one step. Nothing takes focus on mount or on a form reset.