Toggle Group

Groups multiple toggle controls, allowing users to enable one or multiple options.

	<script lang="ts">
  import { ToggleGroup } from "bits-ui";
  import TextB from "phosphor-svelte/lib/TextB";
  import TextItalic from "phosphor-svelte/lib/TextItalic";
  import TextStrikethrough from "phosphor-svelte/lib/TextStrikethrough";
 
  let value: string[] = $state(["bold"]);
</script>
 
<ToggleGroup.Root
  bind:value
  type="multiple"
  class="flex h-input items-center gap-x-0.5 rounded-card-sm border border-border bg-background-alt px-[4px] py-1 shadow-mini"
>
  <ToggleGroup.Item
    aria-label="toggle bold"
    value="bold"
    class="inline-flex size-10 items-center justify-center rounded-9px bg-background-alt transition-all 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"
  >
    <TextB class="size-6" />
  </ToggleGroup.Item>
  <ToggleGroup.Item
    aria-label="toggle italic"
    value="italic"
    class="inline-flex size-10 items-center justify-center rounded-9px bg-background-alt transition-all 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"
  >
    <TextItalic class="size-6" />
  </ToggleGroup.Item>
  <ToggleGroup.Item
    aria-label="toggle strikethrough"
    value="strikethrough"
    class="inline-flex size-10 items-center justify-center rounded-9px bg-background-alt transition-all 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"
  >
    <TextStrikethrough class="size-6" />
  </ToggleGroup.Item>
</ToggleGroup.Root>

Structure

	<script lang="ts">
	import { ToggleGroup } from "bits-ui";
</script>
 
<ToggleGroup.Root>
	<ToggleGroup.Item value="bold">bold</ToggleGroup.Item>
	<ToggleGroup.Item value="italic">italic</ToggleGroup.Item>
</ToggleGroup.Root>

Single & Multiple

The ToggleGroup component supports two type props, 'single' and 'multiple'. When the type is set to 'single', the ToggleGroup will only allow a single item to be selected at a time, and the type of the value prop will be a string.

When the type is set to 'multiple', the ToggleGroup will allow multiple items to be selected at a time, and the type of the value prop will be an array of strings.

Managing Value State

Bits UI offers several approaches to manage and synchronize the component's value state, catering to different levels of control and integration needs.

1. Two-Way Binding

For seamless state synchronization, use Svelte's bind:value directive. This method automatically keeps your local state in sync with the component's internal state.

	<script lang="ts">
	import { ToggleGroup } from "bits-ui";
	let myValue = $state("");
</script>
 
<button onclick={() => (myValue = "item-1")}> Press item 1 </button>
 
<ToggleGroup.Root type="single" bind:value={myValue}>
	<!-- -->
</ToggleGroup.Root>

Key Benefits

  • Simplifies state management
  • Automatically updates myValue when the internal state changes (e.g., via clicking on an item)
  • Allows external control (e.g., toggling an item via a separate button)

2. Change Handler

For more granular control or to perform additional logic on state changes, use the onValueChange prop. This approach is useful when you need to execute custom logic alongside state updates.

	<script lang="ts">
	import { ToggleGroup } from "bits-ui";
	let myValue = $state("");
</script>
 
<ToggleGroup.Root
	type="single"
	value={myValue}
	onValueChange={(v) => {
		myValue = v;
		// additional logic here.
	}}
>
	<!-- ... -->
</ToggleGroup.Root>

Use Cases

  • Implementing custom behaviors on value change
  • Integrating with external state management solutions
  • Triggering side effects (e.g., logging, data fetching)

3. Fully Controlled

For complete control over the component's state, use a Function Binding to manage the value state externally.

	<script lang="ts">
	import { ToggleGroup } from "bits-ui";
	let myValue = $state("");
</script>
 
<ToggleGroup.Root type="single" bind:value={() => myValue, (newValue) => (myValue = newValue)}>
	<!-- ... -->
</ToggleGroup.Root>

When to Use

  • Implementing complex logic
  • Coordinating multiple UI elements
  • Debugging state-related issues

API Reference

ToggleGroup.Root

The root component which contains the toggle group items.

Property Type Description
type required
enum

The type of toggle group.

Default: undefined
value $bindable
union

The value of the toggle group. If the type is 'multiple', this will be an array of strings, otherwise it will be a string.

Default: undefined
onValueChange
function

A callback function called when the value of the toggle group changes. The type of the value is dependent on the type of the toggle group.

Default: undefined
disabled
boolean

Whether or not the switch is disabled.

Default: false
loop
boolean

Whether or not the toggle group should loop when navigating.

Default: true
orientation
enum

The orientation of the toggle group.

Default: horizontal
rovingFocus
boolean

Whether or not the toggle group should use roving focus when navigating.

Default: true
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-orientation
enum

The orientation of the toggle group.

data-toggle-group-root
''

Present on the root element.

ToggleGroup.Item

An individual toggle item within the group.

Property Type Description
value
string

The value of the item.

Default: undefined
disabled
boolean

Whether or not the switch is disabled.

Default: false
ref $bindable
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

Whether the toggle item is in the on or off state.

data-value
''

The value of the toggle item.

data-orientation
enum

The orientation of the toggle group.

data-disabled
''

Present when the toggle item is disabled.

data-toggle-group-item
''

Present on the toggle group item.