Toggle Group

Coordinate one or several pressed actions within a roving focus group.

Usage

Single

Keep one active value while moving and selecting with keyboard or pointer input.

<!-- Toggle Group / Single -->
<script setup lang="ts">
import { ref } from 'vue'
import { ToggleGroupItem, ToggleGroupRoot } from '@sectile/vue/toggle-group'

const items = ['left', 'center', 'right']
const value = ref(['left'])
</script>

<template>
  <ToggleGroupRoot :items="items" v-model="value">
    <ToggleGroupItem v-for="item in items" :key="item" :value="item">{{ item }}</ToggleGroupItem>
  </ToggleGroupRoot>
</template>

Multiple

Select several values independently without collapsing the existing selection.

<!-- Toggle Group / Multiple -->
<script setup lang="ts">
import { ref } from 'vue'
import { ToggleGroupItem, ToggleGroupRoot } from '@sectile/vue/toggle-group'

const items = ['bold', 'italic', 'underline']
const value = ref(['bold', 'italic'])
</script>

<template>
  <ToggleGroupRoot :items="items" v-model="value" multiple>
    <ToggleGroupItem v-for="item in items" :key="item" :value="item">{{ item }}</ToggleGroupItem>
  </ToggleGroupRoot>
</template>

Controlled

Let the parent own the current value and apply accepted changes back to the component.

<!-- Toggle Group / Controlled -->
<script setup lang="ts">
import { ref } from 'vue'
import { ToggleGroupItem, ToggleGroupRoot } from '@sectile/vue/toggle-group'

const items = ['left', 'center', 'right']
const value = ref(['left'])
</script>

<template>
  <ToggleGroupRoot :items="items" v-model="value">
    <ToggleGroupItem v-for="item in items" :key="item" :value="item">{{ item }}</ToggleGroupItem>
  </ToggleGroupRoot>
</template>

API

Vue package: @sectile/vue/toggle-group

Components

ToggleGroupRoot
ToggleGroupItem

Props

`ToggleGroupRootProps`

as: TypePrimitiveAsDefault'div'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
defaultValue: Typereadonly string[]Default[]
Initial value used when the component owns its state.
deselectable: TypebooleanDefaulttrue
Whether selecting the current item again clears it.
disabled: TypebooleanDefaultfalse
Whether interaction is unavailable.
disabledItems: Typereadonly string[]Default[]
Item values excluded from focus and selection.
form: TypestringDefaultundefined
ID of the native form associated with the control.
items: Typereadonly string[]DefaultRequired
Ordered item values managed by the component.
label: TypestringDefaultundefined
Accessible name announced for the control.
modelValue: Typereadonly string[]Defaultundefined
Current value when state is controlled by the parent.
multiple: TypebooleanDefaultfalse
Whether more than one value can be selected.
name: TypestringDefaultundefined
Name used for native form submission.
orientation: Type'horizontal' | 'vertical'Default'horizontal'
Axis used for layout and keyboard movement.
readonly: TypebooleanDefaultfalse
Whether the value can be inspected but not changed.
required: TypebooleanDefaultfalse
Whether the control must contain a valid value before submission.

`ToggleGroupItemProps`

as: TypePrimitiveAsDefault'button'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
disabled: TypebooleanDefaultfalse
Whether interaction is unavailable.
value: TypestringDefaultRequired
Current value exposed by this contract.

Slots

`ToggleGroupRootSlotProps`

disabled: Typeboolean
Whether interaction is unavailable.
highlightedValue: Typestring | null
Value currently highlighted for interaction.
readonly: Typeboolean
Whether the value can be inspected but not changed.
value: Typereadonly string[]
Current value exposed by this contract.

`ToggleGroupItemSlotProps`

disabled: Typeboolean
Whether interaction is unavailable.
highlighted: Typeboolean
Whether this item is highlighted for interaction.
pressed: Typeboolean
Whether the toggle is pressed.
readonly: Typeboolean
Whether the value can be inspected but not changed.
value: Typestring
Current value exposed by this contract.

Events

`ToggleGroupRoot`

highlight: Payloadstring | null
Emitted when the highlighted item changes.
update:modelValue: Payloadreadonly string[]
Emitted when the component requests a new controlled value.

Other types

`ToggleGroupValueChangeHandler`

type ToggleGroupValueChangeHandler = (value: readonly string[]) => void

`ToggleGroupHighlightHandler`

type ToggleGroupHighlightHandler = (value: string | null) => void

Parts

Shared scope: [data-scope="toggle-group"]. Combine it with a part selector to keep styles local to this component.

Part	Selector	Role	Extra attributes
`root`	`[data-part="root"]`	Defines the component boundary and owns its composed parts.	—
`item`	`[data-part="item"]`	Represents one selectable or actionable item.	—

Keyboard interaction

Key	Behavior
`Arrow keys`	Move the active option in the visible orientation.
`Home` / `End`	Move to the first or last eligible option.
`Enter` / `Space`	Select or activate the current option.
`Printable text`	Move to the next matching option when typeahead is available.

Accessibility

The labeled group exposes each item as a pressed button and uses one roving tab stop.

See the corresponding WAI-ARIA pattern for the host accessibility contract.

Toggle Group ​

Usage ​

Single ​

Multiple ​

Controlled ​

API ​

Props ​

ToggleGroupRootProps ​

ToggleGroupItemProps ​

Slots ​

ToggleGroupRootSlotProps ​

ToggleGroupItemSlotProps ​

Events ​

ToggleGroupRoot ​

Other types ​

ToggleGroupValueChangeHandler ​

ToggleGroupHighlightHandler ​

Parts ​

Keyboard interaction ​

Accessibility ​