Segmented Control

A grouped single-choice control for switching between a small set of text or icon-only options.

Quickstart

Set options as a property and listen to value-change.

<rtgl-segmented-control id="role-control" w="320"></rtgl-segmented-control>

<script>
  const control = document.getElementById("role-control");
  control.options = [
    { value: "admin", label: "Admin" },
    { value: "editor", label: "Editor" },
    { value: "viewer", label: "Viewer" },
  ];
  control.selectedValue = "editor";

  control.addEventListener("value-change", (event) => {
    console.log(event.detail.value);
  });

  control.render();
</script>

API

Name	Attribute / Property	Type	Default
Options	`options` (property)	`{ value: any, label?: string, svg?: string, ariaLabel?: string, tooltip?: string, testId?: string }[]`	`[]`
Selected Value	`selected-value` / `selectedValue`	any	-
Group Label	`placeholder`	string	`Segmented control`
No Clear	`no-clear`	boolean	off
Add Option	`addOption` (property)	`{ label?: string }`	-
Disabled	`disabled`	boolean	`false`
Size	`s`	`sm`, `md`, `lg`	`md`
Square	`sq`	boolean	off
Width	`w`	number, `%`, `xs`-`xl`, `f`, CSS length/value	content-based

Events

Event	Detail	Description
`value-change`	`{ value, label, index, item }`	Fires when selection changes or is cleared
`add-option-click`	`{}`	Fires when the add-option segment is clicked

Use s="sm" for a compact 24px-high control or s="lg" for a 40px-high control. The default s="md" control is 32px high, matching default inputs and selects in form rows. This height includes the border and stays the same for text and icon options, including when theme line-height tokens change. Text, icons, and horizontal padding scale with the selected size.

<rtgl-view d="h" av="c" g="lg" wrap>
  <rtgl-segmented-control id="size-md" w="240"></rtgl-segmented-control>
  <rtgl-segmented-control id="size-sm" s="sm" w="200"></rtgl-segmented-control>
  <rtgl-segmented-control id="size-lg" s="lg" w="280"></rtgl-segmented-control>
</rtgl-view>

<script>
  for (const id of ["size-md", "size-sm", "size-lg"]) {
    const control = document.getElementById(id);
    control.options = [
      { value: "left", label: "Left" },
      { value: "center", label: "Center" },
      { value: "right", label: "Right" },
    ];
    control.selectedValue = "center";
    control.render();
  }
</script>

Square Icon Segments

Add sq to make every segment square, matching rtgl-button naming. Square segments are 24px with s="sm", 32px with the default s="md", and 40px with s="lg". This mode is intended for icon-only options and sizes the group from its option count, so w is ignored.

When addOption is enabled in square mode, its segment renders a plus icon and uses the configured add-option label as its accessible name.

<rtgl-view d="h" av="c" g="lg">
  <rtgl-segmented-control id="square-md" sq></rtgl-segmented-control>
  <rtgl-segmented-control id="square-sm" s="sm" sq></rtgl-segmented-control>
  <rtgl-segmented-control id="square-lg" s="lg" sq></rtgl-segmented-control>
</rtgl-view>

<script>
  for (const id of ["square-md", "square-sm", "square-lg"]) {
    const control = document.getElementById(id);
    control.options = [
      { value: "text", svg: "text", ariaLabel: "Text alignment" },
      { value: "music", svg: "music", ariaLabel: "Music alignment" },
      { value: "play", svg: "play", ariaLabel: "Playback alignment" },
    ];
    control.selectedValue = "music";
    control.render();
  }
</script>

Icon-Only Options

Set svg to a registered rtgl-svg key. When svg is present, the segment renders the icon instead of label text.

Use ariaLabel to give each icon-only segment an accessible name. If ariaLabel is omitted, label is used as the accessible-name fallback. Set tooltip when the segment also needs a visual hint on hover.

<rtgl-segmented-control id="mode-control" w="240"></rtgl-segmented-control>

<script>
  const control = document.getElementById("mode-control");
  control.options = [
    {
      value: "text",
      svg: "text",
      ariaLabel: "Text mode",
      tooltip: "Text mode",
    },
    {
      value: "music",
      svg: "music",
      ariaLabel: "Music mode",
      tooltip: "Music mode",
    },
    {
      value: "play",
      svg: "play",
      ariaLabel: "Playback mode",
      tooltip: "Playback mode",
    },
  ];
  control.selectedValue = "music";
  control.render();
</script>

Option Tooltips

Add tooltip to any option to show that text above the segment while it is hovered. Options without tooltip keep the normal hover styling without opening a tooltip.

Selection Behavior

selectedValue controls the active option.
Selecting the active option clears it unless no-clear is enabled.
Values may be primitives or objects and are matched by deep equality.
Disabled controls preserve their selection styling but do not respond to pointer or keyboard input.