# Toggle

A switch control for binary on/off or true/false states.

## Usage

Use standalone.
```svelte
<Toggle {...props} />
```

## Anatomy

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

```svelte
<span class="whole" conditional>
  <span class="left" conditional>{left}</span>
  <button class="main" {...rest} {role} aria-pressed aria-checked aria-label={ariaLabel} bind:this={element} {@attach attach}>
    {children} conditional
  </button>
  <span class="right" conditional>{right}</span>
</span>
```

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `children` | `Snippet` | - | Toggle content; receives value, variant, and button element |
| `left` | `Snippet` | - | Content before the button; receives value, variant, and button element |
| `right` | `Snippet` | - | Content after the button; receives value, variant, and button element |
| `value` | `boolean` | `false` | Bindable pressed state |
| `role` | `<enum>` | `"button"` | ARIA role, either button or switch |
| `ariaLabel` | `string` | - | Accessible label for icon-only or text-less toggles |
| `attach` | `Attachment` | - | Svelte attachment on the button |
| `element` | `HTMLButtonElement` | - | Bindable button element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Bindable variant |
Other `HTMLButtonAttributes` are passed to `<button>` via rest props; `class` is merged onto the control.

For an icon-only or text-less toggle, provide `ariaLabel` so the button has an accessible label.

## Styling

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

### Variant Management

When `value` is `true`, the `active` variant is applied; otherwise, `neutral` is applied. If the `variant` prop is specified, the specified value is used instead of `neutral`.

### Default Class Name

`svs-toggle`

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Wrapper (`whole` `<span>`, when `left` or `right` is rendered): `role="group"`.
- Toggle button (`main` `<button>`): `aria-pressed` reflecting `value` when using the default button role; when `role="switch"`, `role="switch"` and `aria-checked` reflecting `value`; `aria-label` from `ariaLabel` when supplied.

Provide an accessible name yourself for an icon-only or text-less toggle. Pass `ariaLabel`, or pass a name through the button rest props such as `aria-labelledby`.

### Standards Basis

Toggle is built on a native `<button>`, so keyboard and assistive-technology support follows the browser standard for button controls. See the [Concepts standards-first guidance](/docs/concepts) for the library's approach.

## Exports

### Types

```ts
interface ToggleProps extends Omit<
  HTMLButtonAttributes,
  "children" | "value" | "type" | "role" | "aria-pressed" | "aria-checked" | "aria-label"
> {
  children?: Snippet<[boolean, string, HTMLButtonElement | undefined]>; // Snippet<[value,variant,element]>
  left?: Snippet<[boolean, string, HTMLButtonElement | undefined]>; // Snippet<[value,variant,element]>
  right?: Snippet<[boolean, string, HTMLButtonElement | undefined]>; // Snippet<[value,variant,element]>
  value?: boolean; // bindable (false)
  role?: "button" | "switch"; // ("button")
  ariaLabel?: string;
  attach?: Attachment<HTMLButtonElement>;
  element?: HTMLButtonElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  // other HTMLButtonAttributes are passed to <button> via ...rest; `class` is merged onto the button
}
type ToggleReqdProps = never;
type ToggleBindProps = "value" | "variant" | "element";
```

### Others

No additional exports are available.

## Examples

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

### Basic

**Code**

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

  let value = $state(false);
  const styling = {
    main: {
      base: "w-20 h-10 rounded-sm font-medium text-center cursor-pointer",
      neutral: "bg-gray-400",
      active: "bg-teal-500",
    },
  };
  const childStyle = {
    main: {
      base: "flex items-center px-1 w-13 h-7 rounded-full cursor-pointer",
      neutral: "bg-gray-400",
      active: "bg-teal-500",
    },
  };
  const myProps = {
    role: "switch" as const,
    styling: childStyle,
  };
</script>

<div class="flex justify-center items-center gap-5">
  <Toggle bind:value {styling}>
    {#snippet children(value: boolean)}
      {value ? "ON" : "OFF"}
    {/snippet}
  </Toggle>
  <Toggle bind:value {...myProps}>
    {#snippet children(value: boolean)}
      <div class={`transition-[flex] ${value ? "grow" : "grow-0"}`}></div>
      <div class="size-5 rounded-full bg-white"></div>
    {/snippet}
  </Toggle>
</div>
```
### With Interactive Variant

**Code**

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

  let { variant = $bindable() } = $props();
  const variantStyle = {
    neutral: "[--color-bg:oklch(70.7%_0.022_261.325)]",
    active: "[--color-bg:oklch(70.4%_0.14_182.503)]",
    inactive: "[--color-bg:oklch(63.7%_0.237_25.331)]",
    blue: "[--color-bg:oklch(62.3%_0.214_259.815)]",
    yellow: "[--color-bg:oklch(79.5%_0.184_86.047)]",
    sky: "[--color-bg:oklch(68.5%_0.169_237.323)]",
  };
  const styling = {
    whole: {
      base: "flex items-center gap-4",
      ...variantStyle,
    },
    main: "w-10 h-5 rounded-sm font-medium text-center cursor-pointer",
  };
  const myProps = {
    role: "switch" as const,
    ariaLabel: "Activate feature",
    styling,
  };
</script>

<Toggle bind:variant {...myProps}>
  {#snippet children(value: boolean)}
    <div class="flex relative">
      <div class={`absolute top-1/2 left-1/2 w-8 h-2 rounded-full -translate-1/2 -z-10 ${value ? "bg-(--color-bg)" : "bg-gray-400"}`}></div>
      <div class={`transition-[flex] ${value ? "grow" : "grow-0"}`}></div>
      <div class="size-5 rounded-full bg-white"></div>
    </div>
  {/snippet}
  {#snippet right()}
    Activate
  {/snippet}
</Toggle>
```