Button Toggle

Button toggles allow users to select from a group of choices with single or multiple selection.

Day

Week

Month

Overview

Button toggle is a selection component that groups related options into a unified control, allowing users to choose one option from a set of alternatives. It functions similarly to radio buttons but with a more prominent visual treatment that emphasizes the available choices and current selection state.

Button toggles are commonly used for switching between different views of the same information or selecting from a small set of related options where the choices need to be immediately visible and easily comparable.

Usage

forge-button-toggle-group groups forge-button-toggle children into one bordered control, enforcing a single selection by default or several when multiple is set, through outlined, vertical, stretch, dense, and theme — plus native form participation via name and required. Use it for a small, always-visible set of options; reach for a radio group when each option needs a fully written-out label, or a select instead once there are more than a handful of options.

Rules

Limit a button toggle group to a small, glanceable set of options.

Pair every icon-only button toggle with an aria-label.

Use multiple only when more than one option can be true at once, like text formatting.

Don't

Don't use a button toggle group for more than a handful of options — use a select instead.

Don't rely on icons alone without an accessible label on each button toggle.

Don't mix single- and multi-select semantics within the same group.

Selection

A button toggle group enforces a single selection by default — choosing one option deselects any other. Set multiple when more than one option can be true at once, such as a text-formatting toolbar.

Single selection

Only one button toggle in the group is active at a time.

<forge-button-toggle-group aria-label="Choose communication type">
  <forge-button-toggle value="email">
    By email
  </forge-button-toggle>
  <forge-button-toggle value="mail">
    By mail
  </forge-button-toggle>
  <forge-button-toggle value="phone">
    By phone
  </forge-button-toggle>
</forge-button-toggle-group>

Outline

outlined is on by default, drawing a border around the group; set it to false for a borderless button toggle group.

Outlined (default) compared to no-outline.

<forge-button-toggle-group aria-label="Outlined example">
  <forge-button-toggle value="email">
    By email
  </forge-button-toggle>
  <forge-button-toggle value="mail">
    By mail
  </forge-button-toggle>
</forge-button-toggle-group>
<forge-button-toggle-group no-outline aria-label="No outline example">
  <forge-button-toggle value="email">
    By email
  </forge-button-toggle>
  <forge-button-toggle value="mail">
    By mail
  </forge-button-toggle>
</forge-button-toggle-group>

With icons

Slot a forge-icon inside a button toggle to pair its label with a leading icon.

A leading icon reinforces each option's label.

<forge-button-toggle-group aria-label="Choose communication type">
  <forge-button-toggle value="email">
    <forge-icon name="email" slot="start">
    </forge-icon>
    By email
  </forge-button-toggle>
  <forge-button-toggle value="mail">
    <forge-icon name="mail" slot="start">
    </forge-icon>
    By mail
  </forge-button-toggle>
  <forge-button-toggle value="phone">
    <forge-icon name="phone" slot="start">
    </forge-icon>
    By phone
  </forge-button-toggle>
</forge-button-toggle-group>

<script type="module">
import { IconRegistry } from "@tylertech/forge/icon";
import { tylIconMail } from "@tylertech/tyler-icons";
IconRegistry.define([tylIconMail]);
</script>

Dense and vertical

Pair dense with vertical for a compact, stacked button toggle group.

A dense, vertical button toggle group.

<forge-button-toggle-group dense vertical aria-label="Choose communication type">
  <forge-button-toggle value="email">
    By email
  </forge-button-toggle>
  <forge-button-toggle value="mail">
    By mail
  </forge-button-toggle>
  <forge-button-toggle value="phone">
    By phone
  </forge-button-toggle>
</forge-button-toggle-group>

Button toggles allow users to select from a group of choices with single or multiple selection.

import "@tylertech/forge/button-toggle";

Properties

Property	Attribute	Type	Default	Description
`value`	`value`	`unknown`	—	The value of the button toggle.
`selected`	`selected`	`boolean`	`false`	Whether or not the button is selected.
`disabled`	`disabled`	`boolean`	`false`	Whether or not the button is disabled.
`readonly`	`readonly`	`boolean`	`false`	Whether or not the button is readonly.

Events

Name	Type	Description
`forge-button-toggle-select`	`CustomEvent<IButtonToggleSelectEventData>`	Dispatches when the user toggles the button.

Slots

Name	Description
`(default)`	The default/unnamed slot for the button toggle's content.
`start`	Typically reserved for content/icons that render logically before the default slot content.
`end`	Typically reserved content/icons that render logically after the default slot content.

CSS Parts

Name	Description
`::part(root)`	The root container element.
`::part(focus-indicator)`	The focus indicator element.
`::part(state-layer)`	The state layer surface element.

CSS Custom Properties

Name	Description
`--forge-button-toggle-display`	The `display` style for the button toggle container element.
`--forge-button-toggle-min-width`	The minimum width.
`--forge-button-toggle-spacing`	The spacing between the button toggle and its content.
`--forge-button-toggle-padding-block`	The padding on the block axis.
`--forge-button-toggle-padding-inline`	The padding on the inline axis.
`--forge-button-toggle-color`	The color of the button toggle content.
`--forge-button-toggle-background`	The background of the button toggle.
`--forge-button-toggle-cursor`	The cursor of the button toggle.
`--forge-button-toggle-border-width`	The border-width of the button toggle.
`--forge-button-toggle-border-style`	The border-style of the button toggle.
`--forge-button-toggle-border-color`	The border-color of the button toggle.
`--forge-button-toggle-shape`	The shape radius of the button toggle.
`--forge-button-toggle-shape-start-start`	The start-start shape radius of the button toggle.
`--forge-button-toggle-shape-start-end`	The start-end shape radius of the button toggle.
`--forge-button-toggle-shape-end-start`	The end-start shape radius of the button toggle.
`--forge-button-toggle-shape-end-end`	The end-end shape radius of the button toggle.
`--forge-button-toggle-selected-background`	The background of the button toggle when selected.
`--forge-button-toggle-selected-color`	The color of the button toggle content when selected.
`--forge-button-toggle-selected-disabled-background`	The background of the button toggle when selected and disabled.
`--forge-button-toggle-disabled-opacity`	The opacity of the button toggle when disabled.
`--forge-button-toggle-disabled-cursor`	The cursor of the button toggle when disabled.
`--forge-button-toggle-disabled-color`	The color of the button toggle content when disabled.
`--forge-button-toggle-disabled-background`	The background of the button toggle when disabled.
`--forge-button-toggle-transition-duration`	The transition-duration of various properties.
`--forge-button-toggle-transition-timing`	The transition-timing of various properties.

Methods

Name	Returns	Description
`focus(options)`	`void`
`click()`	`void`

Accessibility documentation coming soon.