Report an issue

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.

Value State

The value prop is used to determine which item(s) are currently "on". Bits UI provides flexible options for controlling and synchronizing the value.

Two-Way Binding

Use the bind:value directive for effortless two-way synchronization between your local state and the Toggle Group's internal state.

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

This setup enables toggling the Toggle Group's value to "apple" via the custom button and ensures the local myValue state updates when the state changes through any internal means (e.g., clicking on an item).

Change Handler

You can also use the onValueChange prop to update local state when the Toggle Group's value state changes. This is useful when you don't want two-way binding for one reason or another, or you want to perform additional logic when the Toggle Group changes.

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

Controlled

Sometimes, you may want complete control over the component's value state, meaning you will be "kept in the loop" and be required to apply the state change yourself. While you will rarely need this, it's possible to do so by setting the controlledValue prop to true.

You will then be responsible for updating a local value state variable that is passed as the value prop to the ToggleGroup.Root component.

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

See the Controlled State documentation for more information about controlled states.

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
controlledValue
boolean

Whether or not the value is controlled or not. If true, the component will not update the value state internally, instead it will call onValueChange when it would have otherwise, and it is up to you to update the value prop that is passed to the component.

Default: false
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 delegation 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 delegation 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.