ToggleGroup

A collection of toggle buttons that allows users to select one or multiple options.

Usage

Use standalone, or inside ToggleGroupField.

Svelte

<ToggleGroup {...props} />

Anatomy

The class attribute values represent part names. Other attributes represent their corresponding props.

Svelte

<span class="whole" {...rest} role aria-labelledby aria-describedby={ariaDescId} aria-errormessage={ariaErrMsgId}>
  {#each options as { value, text, ...attrs }}
    <button class="main" {...attrs} type="button" role aria-checked>
      {text} or {children}
    </button>
  {/each}
</span>

Props

Name	Type	Default	Description
`options*`	`SvelteMap`	-	Display text and corresponding values; each option may be a string or a `ToggleOption` with per-button attributes and `text`
`children`	`Snippet`	-	Custom option content; receives value, text, and variant
`values`	`string[]`	-	Bindable selected values
`multiple`	`boolean`	`true`	When true, toggle buttons behave like checkboxes; otherwise, they behave like radio buttons
`events`	`ToggleGroupEvents`	-	Functions that can filter which added or removed values are committed
`ariaDescId`	`string`	-	Description element ID for `aria-describedby`
`ariaErrMsgId`	`string`	-	Bindable error-message element ID for `aria-errormessage`
`attach`	`Attachment`	-	Svelte attachment on each button
`elements`	`HTMLButtonElement[]`	-	Bindable button elements
`styling`	`SVSClass`	-	Styling override
`variant`	`SVSVariant`	`NEUTRAL`	Variant

* required. Other <span> attributes are passed via rest props; class is merged onto the group.

Styling

To learn more, see Styling.

Variant Management

Selected buttons will have the active variant applied. Others are not automatically switched.

Default Class Name

svs-toggle-group

Accessibility

Keyboard Interactions

Key	Description
`ArrowRight` / `ArrowDown`	When `multiple` is `false`, moves focus to the next enabled option and selects it
`ArrowLeft` / `ArrowUp`	When `multiple` is `false`, moves focus to the previous enabled option and selects it
`Home`	When `multiple` is `false`, moves focus to the first enabled option and selects it
`End`	When `multiple` is `false`, moves focus to the last enabled option and selects it
`Space` / `Enter`	Activates the focused button using native button behavior

When multiple is true, arrow-key roving focus is not applied; each enabled toggle remains a normal button in the tab order.

ARIA Roles and Attributes

The component applies these automatically:

Group (whole): role="group" when multiple is true, or role="radiogroup" when multiple is false; also aria-describedby, aria-invalid, and aria-errormessage from props or ToggleGroupField context.
Button (main): role="checkbox" when multiple is true, or role="radio" when multiple is false; also aria-checked and managed tabindex for single-select roving focus.

Each toggle button takes its accessible name from its option text or the children content. Name the standalone group with aria-label or aria-labelledby through rest props. ToggleGroupField with label also names the inner group through its ariaLabelId context.

Exports

Types

TypeScript

interface ToggleOption extends Omit<
  HTMLButtonAttributes,
  "class" | "type" | "role" | "aria-checked" | "aria-invalid" | "aria-errormessage" | "onclick"
> {
  text: string;
}
interface ToggleGroupEvents extends CollectionEvents<string> {}
interface ToggleGroupProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children" | "role" | "aria-describedby" | "aria-invalid" | "aria-errormessage"> {
  options: SvelteMap<string, string | ToggleOption> | Map<string, string | ToggleOption>;
  children?: Snippet<[string, string, string]>; // Snippet<[value,text,variant]>
  values?: string[]; // bindable
  multiple?: boolean; // (true)
  events?: ToggleGroupEvents;
  ariaDescId?: string;
  ariaErrMsgId?: string; // bindable
  attach?: Attachment<HTMLButtonElement>;
  elements?: HTMLButtonElement[]; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
  // other span attributes are passed to the group <span> via ...rest; `class` is merged
  // aria-label / aria-labelledby name the group
}
type ToggleGroupReqdProps = "options";
type ToggleGroupBindProps = "values" | "elements";

Others

No additional exports are available.

Examples

The example code uses Tailwind CSS along with SVSClass.

Basic

With Interactive Variant

Preset for Demo

Free Input

Enter variant as you like