Toggle

View source ARIA design pattern Report an issue

A button that can be toggled between the on and off states.

Preview

Controls

Pressed: false

Toggle Toggle Disabled (false)

Code

MyComponent.svelte

<script lang="ts">
    import { Toggle } from "@niklasburggraaff/svelte-runia";

    let { pressed = $bindable(), disabled }: any = $props();
</script>

{#snippet axe()}
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
        <path d="m14 12-8.5 8.5a2.12 2.12 0 1 1-3-3L11 9" />
        <path d="M15 13 9 7l4-4 6 6h3a8 8 0 0 1-7 7z" />
    </svg>
{/snippet}

<Toggle
    bind:pressed
    {disabled}
    aria-label="Toggle"
    class="bg-background-alt hover:bg-muted active:scale-98 active:bg-dark-10 data-[state=on]:bg-muted data-[state=off]:text-foreground-alt data-[state=on]:text-foreground active:data-[state=on]:bg-dark-10 inline-flex size-10 items-center justify-center rounded-[9px] transition-all"
>
    <Axe />
</Toggle>

Features

• Full keyboard navigation.

Usage

Importing Toggle gives you access the components.

MyComponent.svelte

<script lang="ts">
    import { Toggle } from "@niklasburggraaff/svelte-runia";
</script>

<Toggle aria-label="...">
    ...
</Toggle>

• The Toggle must be passed a labelledByContent, aria-label, or aria-labelledby prop
  • labelledByContent should be passed if the toggle contains text describing what the toggle does
  • Otherwise, the aria-label should describe what the toggle does when pressed
  • If the description is already in an element, use aria-labelledby to reference the id of that element

Caution

Do NOT change the aria-label (or content if labelledByContent) based on the state of the toggle. The aria-pressed attribute is handled by the component to determine the state.

As an example, if the toggle is for arming an axe with the aria-label set to "Arm axe". The aria-pressed attributes indicates if the axes is armed. Now let’s say when the toggle is pressed, the aria-label is changed to "Disarm axe". The aria-pressed attribute will be true. So is it true that the axe is disarmed? No, of course not!

API

Toggle

button

The Toggle component the entire toggle.

Props

• pressed:boolean = false (bindable)
  • Whether the toggle is pressed.
• disabled:boolean = false
  • When true, prevents the user from interacting with the toggle.
• labelledByContent:true (2)
  • Indicates the toggle contains text describing what the toggle does when pressed.
• aria-label:string (1)
  • Description of what the toggle does when pressed.
• aria-labelledby:string (1)
  • ID of element that describes what the toggle does when pressed.
• element:HTMLButtonElement (bindable)
  • The rendered button element.

Prop	Type	Default	Description
pressed	boolean (bindable)	false	Whether the toggle is pressed.
disabled	boolean	false	When true, prevents the user from interacting with the toggle.
labelledByContent (1)	true	-	Indicates the toggle contains text describing what the toggle does when pressed.
aria-label (1)	string	-	Description of what the toggle does when pressed.
aria-labelledby (1)	string	-	ID of element that describes what the toggle does when pressed.
element	HTMLButtonElement (bindable)	-	The rendered button element.

(1)- One of labelledByContent aria-label aria-labelledby is required.

Data attributes

• data-state: "on" | "off"
  • The state of the toggle.
• data-disabled
  • Present when the toggle is disabled.

Attribute	Values	Description
[data-state]	"on" | "off"	The state of the toggle.
[data-disabled]	-	Present when the toggle is disabled.

Accessibility

Adheres to the Toggle button in WAI-ARIA Button Pattern.

Keyboard interactions

• Enter/Space :

  Attempts to toggle the state of the toggle.

Keys	Condition	Action
Enter / Space	If focus on a Trigger	Attempts to toggle the state of the toggle.

Other events

• Toggle. onclick :

  Attempts to toggle the state of the toggle.

Component	Event	Action
Toggle	onclick	Attempts to toggle the state of the toggle.

ARIA attributes

Toggle

• aria-pressed: "on" | "off"
  • "on" when the toggle is pressed and "off" when the toggle is not pressed.
• aria-label: string
  • Description of what the toggle does when pressed.
• aria-labelledby: string
  • ID of element that describes what the toggle does when pressed.

Attribute	Type	Description
aria-pressed	"on" | "off"	"on" when the toggle is pressed and "off" when the toggle is not pressed.
aria-label	string	Description of what the toggle does when pressed.
aria-labelledby	string	ID of element that describes what the toggle does when pressed.

Examples

Pressed by default

Use the pressed prop to set the initial state of the toggle to be pressed.

Code

<Toggle pressed ...>
    ...
</Toggle>

Preview

Control the pressed state

Add label

Set the aria-label prop to the description of what the toggle does when pressed.

Code

<Toggle aria-label="arm axe">...</Toggle>

Preview

Label by element

Set the aria-labelledby prop to the id of an element that describes what the toggle does when pressed.

Code

<label id="axe-label">Arm axe</label>
<Toggle aria-labelledby="axe-label">...</Toggle>

Preview

Arm axe

Label by content

Set the labelledByContent prop to true to indicate the toggle contains text describing what the toggle does when pressed.

Code

<Toggle labelledByContent>Arm axe</Toggle>

Preview

Arm axe