Skip to main content

Starwind UI v3.0 is now available! Migration guide

On this page

Toggle Group Primitive

View Markdown

Toggle Group is a Starwind Runtime primitive in the controlled-value-group contract family. Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.

Anatomy

Use the Astro primitive adapter to render ToggleGroup anatomy with the Runtime wiring included.

---
import { ToggleGroup } from "@starwind-ui/astro/toggle-group";
---


<ToggleGroup.Root />

API Reference

Root

The main element that owns the Toggle Group Runtime instance.

Default element
div
Discovery hook
data-sw-toggle-group
Role
group

Props

Prop Type Default Toggle
value ToggleGroupValue -
Description
Controls the current Toggle Group value.
Kind
control
Targets
-
Full type
ToggleGroupValue
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue
defaultValue ToggleGroupValue -
Description
Sets the initial Toggle Group value for uncontrolled usage.
Kind
control
Targets
-
Full type
ToggleGroupValue
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue
disabled boolean false
Description
Disables the Root part.
Kind
option
Targets
-
Full type
boolean
loopFocus boolean true
Description
Lets keyboard focus wrap around the Toggle Group items.
Kind
option
Targets
-
Full type
boolean
multiple boolean false
Description
Allows multiple Toggle Group values to be selected.
Kind
option
Targets
-
Full type
boolean
orientation "horizontal" | "vertical" "horizontal"
Description
Sets the Toggle Group orientation.
Kind
option
Targets
-
Full type
"horizontal" | "vertical"
onValueChange (value: ToggleGroupValue, details: ToggleGroupValueChangeDetails) => void -
Description
Runs when the Toggle Group value changes.
Kind
callback
Targets
-
Full type
(value: ToggleGroupValue, details: ToggleGroupValueChangeDetails) => void
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue

Events

Event Callback Value Toggle
valueChange onValueChange value: ToggleGroupValue
Description
Fires when the value changes for Toggle Group.
DOM event
starwind:value-change
Details type
ToggleGroupValueChangeDetails
Timing
before-state-commit
Cancelable
Yes
Cancellation sequence
  1. Check internal eligibility and intent.
  2. Create one details object for the proposal.
  3. Call the Runtime callback with the details object when the controller exposes one.
  4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
  5. Read details.isCanceled, including cancellation caused by preventDefault().
  6. Apply the accepted state.
  7. Notify Runtime subscribers and other accepted-only observers.

State

State Type Props Toggle
value ToggleGroupValue value / defaultValue
Description
Tracks the current Toggle Group value.
Initial attribute
data-default-value
Runtime getter
getValue
Runtime setter
setValue
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue

Data Attributes

Runtime hooks
Attribute Value Description
data-sw-toggle-group - Marks the Root part so Starwind Runtime can find it.
State
Attribute Value Description
data-value - Reflects the value state on the Root part.
Metadata
Attribute Value Description
data-default-value - Reflects the default value prop on the Root part.
data-disabled - Reflects the disabled prop on the Root part.
data-loop-focus - Reflects the loop focus prop on the Root part.
data-multiple - Reflects the multiple prop on the Root part.
data-orientation - Reflects the orientation prop on the Root part.

Runtime API

Factory
createToggleGroup
Import
@starwind-ui/runtime/toggle-group
Root hook
root data-sw-toggle-group
Option props
defaultValue, disabled, loopFocus, multiple, orientation, value

Runtime Setters

Method Target Description
setValue state: value Updates the current Toggle Group value from Runtime code.
setDisabled prop: disabled Updates whether Toggle Group is disabled from Runtime code.
setLoopFocus prop: loopFocus Updates Toggle Group keyboard focus wrapping from Runtime code.
setMultiple prop: multiple Updates whether Toggle Group allows multiple values from Runtime code.
setOrientation prop: orientation Updates the Toggle Group orientation from Runtime code.

Related Styled Components

Component Relationship
Toggle Group Composite

Changelog

View version history v1.0.0 4 releases

v1.0.0

  • Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.

v0.1.2

  • Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
  • Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.

v0.1.1

  • Included the generated React context provider in vendored Toggle Group output so items receive current group state.

v0.1.0

  • Introduced single and multiple grouped toggle state with coordinated keyboard navigation.