# 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](/docs/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

```ts
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

**Code**

```svelte src=ToggleGroupBasic.svelte
<script lang="ts">
  import { ToggleGroup } from "svseeds";

  const styling = {
    whole: "flex gap-2 p-4 rounded-md border",
    main: {
      base: "px-2 rounded-sm cursor-pointer",
      neutral: "bg-gray-400",
      active: "bg-teal-500",
    },
  };
  const myProps = {
    options: new Map([
      ["1", "option1"],
      ["2", "option2"],
      ["3", "option3"],
    ]),
    values: ["3"],
    styling,
  };
</script>

<ToggleGroup {...myProps} />
```
### With Interactive Variant

**Code**

```svelte src=ToggleGroupPract.svelte
<script lang="ts">
  import { ToggleGroup } from "svseeds";

  let { variant = $bindable() } = $props();
  const fruits = {
    "01": "🍎",
    "02": "🍊",
    "03": "🍌",
    "04": "🍇",
    "05": "🍑",
    "06": "🍈",
  };
  const variantStyle = {
    neutral: "bg-gray-400",
    active: "bg-teal-500",
    inactive: "bg-red-500",
    blue: "bg-blue-500",
    yellow: "bg-yellow-500",
    sky: "bg-sky-500",
  };
  const styling = {
    whole: "grid grid-cols-3 gap-2 p-4 rounded-md border border-gray-400",
    main: {
      base: "px-2 rounded-full cursor-pointer",
      ...variantStyle,
    },
  };
  const myProps = {
    options: new Map([
      ["01", "Apple"],
      ["02", "Orange"],
      ["03", "Banana"],
      ["04", "Grape"],
      ["05", "Peach"],
      ["06", "Melon"],
    ]),
    multiple: false,
    styling,
  };
</script>

<ToggleGroup {variant} {...myProps}>
  {#snippet children(value: string, text: string)}
    {fruits[value as keyof typeof fruits]} {text}
  {/snippet}
</ToggleGroup>
```