Lily Design System™

Segment Group Item

SegmentGroupItem is a single segment option within a SegmentGroup. It renders as a <button> with role="radio" and aria-checked, following the WAI-ARIA radio group pattern. Each item represents one mutually exclusive option in the segmented control.

Use SegmentGroupItem inside a SegmentGroup to build custom segmented controls such as view mode toggles (grid/list), filter selections, or display density controls.

Example

Show demo markup 
<button class="segment-group-item" role="radio" aria-checked="true">Grid</button>
Usage example 
<script lang="ts">
    import SegmentGroup from "../SegmentGroup/SegmentGroup.svelte";
    import SegmentGroupItem from "./SegmentGroupItem.svelte";
    let view = $state("grid");
</script>

<SegmentGroup label="View">
    <SegmentGroupItem
        checked={view === "grid"}
        value="grid"
        onclick={() => (view = "grid")}
    >Grid</SegmentGroupItem>
    <SegmentGroupItem
        checked={view === "list"}
        value="list"
        onclick={() => (view = "list")}
    >List</SegmentGroupItem>
</SegmentGroup>
Show Svelte source 
// In your Svelte component:
import SegmentGroupItem from "lily-design-system-svelte-headless/components/SegmentGroupItem/SegmentGroupItem.svelte";

<SegmentGroupItem>
  <!-- content -->
</SegmentGroupItem>

Usage

View mode toggle showing Grid and List options:

<SegmentGroup label="View mode">
  <SegmentGroupItem checked={mode === 'grid'} value="grid" onclick={() => mode = 'grid'}>
    Grid
  </SegmentGroupItem>
  <SegmentGroupItem checked={mode === 'list'} value="list" onclick={() => mode = 'list'}>
    List
  </SegmentGroupItem>
</SegmentGroup>

Display density selector with a disabled option:

<SegmentGroup label="Display density">
  <SegmentGroupItem checked={density === 'compact'} value="compact" onclick={() => density = 'compact'}>
    Compact
  </SegmentGroupItem>
  <SegmentGroupItem checked={density === 'normal'} value="normal" onclick={() => density = 'normal'}>
    Normal
  </SegmentGroupItem>
  <SegmentGroupItem checked={false} value="spacious" disabled>
    Spacious
  </SegmentGroupItem>
</SegmentGroup>

Props

  • checked: boolean (default false) -- whether this segment is currently selected
  • value: string (default "") -- value associated with this segment, exposed as data-value
  • disabled: boolean (default false) -- whether the segment is disabled
  • children: slot (required) -- label content to render inside the button
  • ...restProps: unknown -- additional attributes spread onto the <button> element

Keyboard Interactions

  • Tab: Focus moves to the checked segment (or first segment if none checked)
  • Arrow Left / Arrow Right: Consumer should implement arrow key navigation on the parent SegmentGroup
  • Space / Enter: Activates the focused segment (native button behavior)

ARIA

  • role="radio" -- identifies this button as a radio-like option within a radiogroup
  • aria-checked -- indicates whether this segment is selected (true) or not (false)
  • Roving tabindex -- only the checked item has tabindex="0", others have tabindex="-1"

When to Use

  • Use SegmentGroupItem inside a SegmentGroup to represent one selectable segment option.
  • Use SegmentGroupItem for custom toggle button UIs such as view mode switches, filter options, or density controls.
  • Use SegmentGroupItem when each option needs a value attribute for programmatic identification.

When Not to Use

  • Do not use SegmentGroupItem outside of a SegmentGroup -- it requires the parent radiogroup context for proper ARIA semantics.
  • Do not use SegmentGroupItem for standalone toggle buttons -- use ToggleButton instead.
  • Do not use SegmentGroupItem for standard radio inputs in a form -- use RadioInput instead.

Headless

The SegmentGroupItem headless component provides a <button> with role="radio", aria-checked, roving tabindex, and data-value for CSS targeting. The consumer provides all visual styling for the segment button, including selected and disabled states.

Styles

The consumer provides all CSS styling. The component renders with a .segment-group-item class for targeting. No default styles are included — this is a fully headless component.

Testing

  • Verify the component renders a <div> element with class segment-group-item
  • Verify role="radio"` -- identifies this button as a radio-like option within a radiogroup
  • Verify keyboard interactions work correctly
  • Verify pass-through attributes are applied

Advice

  • Designers: Make the selected segment visually distinct with a filled background or bold text, and ensure disabled segments are visually muted.
  • Developers: Use the checked prop to control aria-checked and tabindex; ensure only one item in the group has checked={true} at a time.

Implementation Notes

  • Renders a <button> element with role="radio" for ARIA semantics
  • aria-checked reflects the checked prop to indicate selection state
  • Uses roving tabindex: tabindex="0" when checked, tabindex="-1" otherwise
  • data-value attribute exposes the segment value for CSS styling or JS queries
  • Supports disabled prop to prevent interaction
  • Spreads restProps onto the button for consumer customization

Related components

  • segment-group — a group of mutually exclusive segment options

References

  • WAI-ARIA Radio Group Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/radio/

Canonical contract

Generated from this component's canonical metadata — the machine-checked source the implementations are held to.

Metadata

  • Component: segment-group-item
  • PascalCase: SegmentGroupItem
  • Description: one selectable segment in a segment group
  • Status: stable — exercised in composed page flows under e2e and axe, beyond the per-component checks
  • HTML tag: <button>
  • CSS class: .segment-group-item
  • Interactive: yes

ARIA

  • role="radio" -- identifies this button as a radio-like option within a radiogroup
  • aria-checked -- indicates whether this segment is selected (true) or not (false)
  • Roving tabindex -- only the checked item has tabindex="0", others have tabindex="-1"

Keyboard

  • Tab: Focus moves to the checked segment (or first segment if none checked)
  • Arrow Left / Arrow Right: Consumer should implement arrow key navigation on the parent SegmentGroup
  • Space / Enter: Activates the focused segment (native button behavior)

Props

  • checked: boolean (default false) -- whether this segment is currently selected
  • value: string (default "") -- value associated with this segment, exposed as data-value
  • disabled: boolean (default false) -- whether the segment is disabled
  • children: slot (required) -- label content to render inside the button
  • ...restProps: unknown -- additional attributes spread onto the <button> element