Skip to content
Destyler UI Destyler UI Destyler UI
Docs
Toggle

Toggle

A toggle group is used to toggle either one option or multiple options.

Features

Install

Install the component from your command line.

Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/toggle-group @destyler/vue
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/toggle-group @destyler/react
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/toggle-group @destyler/svelte
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/toggle-group @destyler/solid

Anatomy

Import all parts and piece them together.

<script setup lang="ts">
import * as toggle from '@destyler/toggle'
import { normalizeProps, useMachine } from '@destyler/vue'
import { computed, useId } from 'vue'


const [state, send] = useMachine(toggle.machine({
  id: useId(),
}))
const api = computed(() => toggle.connect(state.value, send, normalizeProps))
</script>


<template>
  <div v-bind="api.getRootProps()">
    <button v-bind="api.getItemProps({ value: '1' })" > </button>
    <button v-bind="api.getItemProps({ value: '2' })" > </button>
    <button v-bind="api.getItemProps({ value: '3' })" > </button>
  </div>
</template>
import { normalizeProps, useMachine } from '@destyler/react'
import * as toggle from '@destyler/toggle'
import { useId } from 'react'


export default function TogglePage() {
  const [state, send] = useMachine(toggle.machine({
    id: useId(),
  }))


  const api = toggle.connect(state, send, normalizeProps)


  return (
    <div {...api.getRootProps()} >
      <button {...api.getItemProps({ value: '0' })}></button>
      <button {...api.getItemProps({ value: '1' })}></button>
      <button {...api.getItemProps({ value: '2' })}></button>
    </div>
  )
}
<script lang="ts">
  import * as toggle from "@destyler/toggle";
  import { normalizeProps, useMachine } from "@destyler/svelte";


  const id = $props.id();
  const [state, send] = useMachine(toggle.machine({
    id,
  }));


  const api = $derived(toggle.connect(state, send, normalizeProps));
</script>


<div {...api.getRootProps()} >
  <button {...api.getItemProps({ value: '0' })}></button>
  <button {...api.getItemProps({ value: '1' })}></button>
  <button {...api.getItemProps({ value: '2' })}></button>
</div>
import { normalizeProps, useMachine } from '@destyler/solid'
import * as toggle from '@destyler/toggle'
import { createMemo, createUniqueId } from 'solid-js'


export default function TogglePage() {
  const [state, send] = useMachine(toggle.machine({
    id: createUniqueId(),
  }))


  const api = createMemo(() => toggle.connect(state, send, normalizeProps))


  return (
    <div {...api().getRootProps()} >
      <button {...api().getItemProps({ value: '0' })} ></button>
      <button {...api().getItemProps({ value: '1' })} ></button>
      <button {...api().getItemProps({ value: '2' })} ></button>
    </div>
  )
}

Change the orientation

By default, the toggle group is assumed to be horizontal. To change the orientation to vertical, set the orientation property in the destyler’s context to vertical.

const [state, send] = useMachine(
  toggle.machine({
    orientation: "vertical",
  }),
)

Listening for value changes

When the pressed toggle in the group changes, onValueChange callback is invoked.

const [state, send] = useMachine(
  toggle.machine({
    onValueChange(details) {
      // details => { value: string[] }
      console.log(details.value)
    },
  }),
)

Allowing multiple selection

Set the multiple property in the destyler’s context to true to allow multiple options to be toggled.

const [state, send] = useMachine(
  toggle.machine({
    multiple: true,
  }),
)

Disabling the toggle group

Set the disabled property in the destyler’s context to true to disable the toggle group.

const [state, send] = useMachine(
  toggle.machine({
    disabled: true,
  }),
)

Disabling a toggle

Set the disabled property in the getToggleProps function to true to disable a toggle.

<!-- ... -->
<template>
  <div v-bind="api.getRootProps()">
    <button v-bind="api.getItemProps({ value: '1', disabled: true })" > </button>
    <!-- ... -->
  </div>
</template>
export default function TogglePage() {
  // ...
  return (
    <div {...api.getRootProps()} >
      <button {...api.getItemProps({ value: '0', disabled: true })}></button>
      // ...
    </div>
  )
}
<!-- ... -->
<div {...api.getRootProps()} >
  <button {...api.getItemProps({ value: '0', disabled: true })}></button>
  <!-- ... -->
</div>
<!-- ... -->
export default function TogglePage() {
  // ...
  return (
    <div {...api().getRootProps()} >
      <button {...api().getItemProps({ value: '0', disabled: true })} ></button>
      // ...
    </div>
  )
}

Disabling focus loop

The toggle group uses roving focus management by default. To disable this, set the rovingFocus property in the destyler’s context to false.

const [state, send] = useMachine(
  toggle.machine({
    rovingFocus: false,
  }),
)

Styling guide

Earlier, we mentioned that each Toggle Group part has a data-part attribute added to them to select and style them in the DOM.

Pressed State

The toggle is pressed, the data-state attribute is applied to the toggle button with on or off values.

[data-part="toggle"][data-state="on"] {
  /* styles for toggle button */
}

Focused State

When a toggle button is focused, the data-focus is applied to the root and matching toggle button.

[data-part="root"][data-focus] {
  /* styles for the root */
}


[data-part="toggle"][data-focus] {
  /* styles for the toggle */
}

Disabled State

When a toggle button is disabled, the data-disabled is applied to the root and matching toggle button.

[data-part="root"][data-disabled] {
  /* styles for the root */
}


[data-part="toggle"][data-disabled] {
  /* styles for the toggle */
}

Methods and Properties

Machine Context

The toggle machine exposes the following context properties:

ids
Partial<{ root: string; item: (value: string) => string; }>
The ids of the elements in the toggle. Useful for composition.
disabled
boolean
Whether the toggle is disabled.
value
string[]
The values of the toggles in the group.
onValueChange
(details: ValueChangeDetails) => void
Function to call when the toggle is clicked.
loopFocus(default: true)
boolean
Whether to loop focus inside the toggle group.
rovingFocus(default: true)
boolean
Whether to use roving tab index to manage focus.
orientation(default: "horizontal")
Orientation
The orientation of the toggle group.
multiple
boolean
Whether to allow multiple toggles to be selected.
dir(default: "ltr")
"ltr" | "rtl"
The document's text/writing direction.
id
string
The unique identifier of the machine.
getRootNode
() => ShadowRoot | Node | Document
A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

Machine API

The toggle api exposes the following methods:

value
string[]
The value of the toggle group.
setValue
(values: string[]) => void
Function to set the value of the toggle group.
getItemState
(props: ItemProps) => ItemState
Returns the state of the toggle item.

Data Attributes

Root

attribute
description
data-scope
toggle
data-part
root
data-disabled
Present when disabled
data-orientation
The orientation of the toggle
data-focus
Present when focused

Item

attribute
description
data-scope
toggle
data-part
item
data-focus
Present when focused
data-disabled
Present when disabled
data-orientation
The orientation of the item
data-state
"on" | "off"

Accessibility

Keyboard Interaction

name
desc
Tab
Moves focus to either the pressed item or the first item in the group.
Space
Activates/deactivates the item.
Enter
Activates/deactivates the item.
ArrowDown
Moves focus to the next item in the group.
ArrowRight
Moves focus to the next item in the group.
ArrowUp
Moves focus to the previous item in the group.
ArrowLeft
Moves focus to the previous item in the group.
Home
Moves focus to the first item.
End
Moves focus to the last item.

Switch

Calendar