ToggleGroupField

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

Toggle Group Field

Select your options

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.

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.

Exports

Types

TypeScript

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

Toggle Group Field

Select your options

With Interactive Variant

Preset for Demo

Free Input

Enter variant as you like

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}