Prototype Library

Button Toggle

The inherited Ecology segmented single-select — one-of-N choices rendered as a row of connected buttons. Form-associated and following the WAI-ARIA radiogroup pattern; the selected segment fills with forest green from --color-primary. In the Atlas it switches the map / form entry paths.

Inherited wc import '@esa/ecology/esa-button-toggle';

Preview

<esa-button-toggle label="Entry path"></esa-button-toggle>

<script>
  el.options = [
    { value: 'map', label: 'Map' },
    { value: 'form', label: 'Form' },
    { value: 'compare', label: 'Compare' },
  ];
  el.value = 'map';
</script>

Sizes

Four sizes share the form scale. Default is md.

<esa-button-toggle size="xs"></esa-button-toggle>
<esa-button-toggle size="sm"></esa-button-toggle>
<esa-button-toggle size="md"></esa-button-toggle>
<esa-button-toggle size="lg"></esa-button-toggle>

States

<esa-button-toggle label="Default"></esa-button-toggle>
<esa-button-toggle label="With hint" hint="Pick an entry path"></esa-button-toggle>
<esa-button-toggle label="Disabled" disabled></esa-button-toggle>

API

PropTypeDefaultDescription
options { value: string, label: string }[] [] The segments. Set as a property (it is an array, not an attribute).
value string '' Selected option's value. Single-select; bound to the form value.
label string '' Optional visible label above the group; becomes the radiogroup name.
hint string '' Optional helper text below the group.
size 'xs' | 'sm' | 'md' | 'lg' 'md' Control size (shared form scale).
required boolean false Marks the field required (adds an asterisk and aria-required).
disabled boolean false Disables every segment.

Events

EventTypeDefaultDescription
change CustomEvent<{ value: string }> — Fired when the selection changes. Composed and bubbling; detail.value is the newly selected value.

Accessibility

  • Renders role="radiogroup" wrapping role="radio" buttons with aria-checked reflecting selection.
  • Roving tabindex: only the selected (or first) segment is tab-reachable; Arrow keys move selection through the group, wrapping at the ends.
  • Home and End jump to the first and last segments; Enter and Space select the focused segment.
  • The label becomes the group's accessible name; hint is wired with aria-describedby.
  • Best for small fixed option sets — past about six options, prefer a select.