# ToggleGroupField

A form control for selecting one or multiple options from a set of toggle buttons.

## Usage

Use standalone, or wrap `ToggleGroup` to share state.
```svelte
<ToggleGroupField {...props} />

<ToggleGroupField {...props}>
  <ToggleGroup {...props} />
</ToggleGroupField>
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<div class="whole">
  <div class="top" conditional>
    <label class="label" conditional>
      {label}
      <span class="extra" conditional>{extra}</span>
    </label>
    <span class="aux" conditional>{aux}</span> Snippet args: [values, variant, element]
  </div>
  <div class="middle">
    <span class="left" conditional>{left}</span>
    <input style="display:none" aria-hidden="true" oninvalid />
    {#if name}
      {#each values as value}
        <input type="hidden" {name} {value} />
      {/each}
    {/if}
    {#if children}
      {@render children()}
    {:else if options}
      <ToggleGroup {options} {multiple} {...toggleGroup} />
    {/if}
    <span class="right" conditional>{right}</span>
  </div>
  <div class="bottom" conditional: has text, or always when reserve>{bottom}</div>
</div>
```

`aux`, `left`, and `right` snippets receive `[values, variant, element]`. When a declarative child is supplied, the field's `multiple` and `toggleGroup` props are ignored.

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `options` | `SvelteMap` | - | Display text and corresponding values; each option may be a string or a `ToggleOption` |
| `label` | `string` | - | Field label |
| `extra` | `string` | - | Extra text shown with the label |
| `aux` | `Snippet` | - | Auxiliary content; receives values, variant, and input element |
| `left` | `Snippet` | - | Content before the inner group; receives values, variant, and input element |
| `right` | `Snippet` | - | Content after the inner group; receives values, variant, and input element |
| `bottom` | `string` | - | Bottom message |
| `reserve` | `boolean` | `false` | Renders the bottom element even without a message to prevent layout shift |
| `values` | `string[]` | - | Bindable selected values |
| `multiple` | `boolean` | `true` | When true, toggle buttons behave like checkboxes; otherwise, they behave like radio buttons |
| `validations` | `ToggleGroupFieldValidation[]` | - | Validation functions used to validate input values |
| `constraints` | `ToggleGroupFieldConstraint[]` | - | Constraint functions used to restrict selected values |
| `name` | `string` | - | The `name` attribute for form submission |
| `elements` | `HTMLButtonElement[]` | - | Bindable button elements |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Bindable variant |
| `toggleGroup` | `ToggleGroupProps` | - | Props for the default inner `ToggleGroup` when no `children` are supplied; ignored if a child control is provided |
| `children` | `Snippet` | - | Use the compound form to provide a child `ToggleGroup` that shares the field state |
`constraints` run only on the add (click) path, so in single-select mode they gate each newly selected value but not removals or the final set. To forbid a specific value outright, mark that option `disabled`; to validate the resulting selection, use `validations`.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

In the initial state or when there is no input value, `neutral` is applied. If constraints do not allow the input, `inactive` is applied. After a value is entered, the variant switches to `active` if validation succeeds, or remains `neutral` temporarily if validation fails. During form validation, `inactive` is applied when validation fails. If the `variant` prop is specified, the specified value is used instead of `neutral`.

### Default Class Name

`svs-toggle-group-field`

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Field (`whole` `<div>`): `role="group"` and `aria-labelledby` pointing to the label part when label text is present.
- Validity proxy input: `aria-hidden="true"`.

Provide `label` text for the field's accessible name; the component wires that label to the group instead of requiring an author-passed `aria-label`. Roving-focus keyboard behavior and toggle state ARIA for the default control are documented on [ToggleGroup](/docs/toggle-group).

## Exports

### Types

```ts
type ToggleGroupFieldValidation = SVSFieldValidation<string[]>;
type ToggleGroupFieldConstraint = SVSFieldConstraint;
interface ToggleGroupFieldProps {
  options?: SvelteMap<string, string | ToggleOption> | Map<string, string | ToggleOption>;
  label?: string;
  extra?: string;
  aux?: Snippet<[string[], string, HTMLInputElement | undefined]>; // Snippet<[values,variant,element]>
  left?: Snippet<[string[], string, HTMLInputElement | undefined]>; // Snippet<[values,variant,element]>
  right?: Snippet<[string[], string, HTMLInputElement | undefined]>; // Snippet<[values,variant,element]>
  bottom?: string;
  reserve?: boolean; // (false)
  values?: string[]; // bindable
  multiple?: boolean; // (true)
  validations?: ToggleGroupFieldValidation[];
  constraints?: ToggleGroupFieldConstraint[];
  name?: string;
  elements?: HTMLButtonElement[]; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  toggleGroup?: Omit<
    ToggleGroupProps,
    ToggleGroupReqdProps | ToggleGroupBindProps | "ariaDescId" | "ariaErrMsgId" | "multiple" | "variant" | "events"
  >;
  children?: Snippet;
}
type ToggleGroupFieldReqdProps = never;
type ToggleGroupFieldBindProps = "values" | "variant" | "elements";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

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

  const styling = {
    label: "font-bold",
    middle: "mt-1 px-2 flex flex-col accent-teal-500",
    main: "outline-hidden",
    bottom: "mt-1 text-xs",
  };
  const myProps = {
    options: new Map([
      ["1", "option1"],
      ["2", "option2"],
      ["3", "option3"],
    ]),
    label: "Toggle Group Field",
    bottom: "Select your options",
    values: ["3"],
    styling,
  };
  const childStyle = {
    whole: "flex gap-2 rounded-md",
    main: {
      base: "px-2 rounded-sm cursor-pointer",
      neutral: "bg-gray-400",
      active: "bg-teal-500",
    },
  };
  const svsToggleGroup = {
    styling: childStyle,
  };
</script>

<ToggleGroupField toggleGroup={svsToggleGroup} {...myProps} />
```
### With Interactive Variant

**Code**

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

  let { variant = $bindable() } = $props();
  let values = $state(["03"]);
  let form: HTMLFormElement | undefined = $state();
  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 = {
    label: {
      base: "font-bold",
      inactive: "text-red-500",
    },
    extra: "ps-1 text-gray-400",
    middle: "mt-1 px-2 flex flex-col accent-teal-500",
    main: "outline-hidden",
    bottom: {
      base: "mb-1 text-xs",
      inactive: "text-red-500",
    },
  };
  const myProps = {
    options: new Map([
      ["01", "Apple"],
      ["02", "Orange"],
      ["03", "Banana"],
      ["04", "Grape"],
      ["05", "Peach"],
      ["06", "Melon"],
    ]),
    label: "Favorite Fruits",
    extra: "(optional)",
    bottom: "Choose your favorites",
    validations: [({ value }: { value: string[] }) => (value.length === 1 && value[0] === "03" ? "You can't just pick a banana" : "")],
    styling,
  };
  const childStyle = {
    whole: "grid grid-cols-3 gap-2",
    main: {
      base: "px-2 rounded-full text-nowrap truncate cursor-pointer",
      ...variantStyle,
    },
  };
  const svsToggleGroup = {
    children,
    styling: childStyle,
  };
  const attrButton = {
    class: "px-2 rounded-md bg-teal-500 cursor-pointer",
    type: "button" as const,
    onclick: () => form?.checkValidity(),
  };
</script>

<form bind:this={form} class="flex flex-col">
  <ToggleGroupField bind:variant bind:values toggleGroup={svsToggleGroup} {...myProps} />
  <div class="mt-5">
    <p>values: {values}</p>
    <button {...attrButton}>validate</button>
  </div>
</form>

{#snippet children(value: string, text: string)}
  {fruits[value as keyof typeof fruits]} {text}
{/snippet}
```