ToggleGroup Primitive
ToggleGroup is a Starwind Runtime primitive in the controlled-value-group contract family.
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 />Use the React primitive adapter when ToggleGroup state participates in React rendering.
import { ToggleGroup } from "@starwind-ui/react/toggle-group";
export function Example() { return ( <ToggleGroup.Root /> );}Render the ToggleGroup data-sw-* contract yourself, then initialize createToggleGroup.
<div data-sw-toggle-group role="group"></div>
<script type="module"> import { createToggleGroup } from "@starwind-ui/runtime/toggle-group";
const root = document.querySelector("[data-sw-toggle-group]"); if (root) { createToggleGroup(root); }</script>API Reference
Root
The main element that owns the ToggleGroup Runtime instance.
- Default element
- div
- Discovery hook
- data-sw-toggle-group
- Role
- group
Props
Prop Type Default Toggle
value ToggleGroupValue -
- Description
- Controls the current ToggleGroup value.
- Kind
- control
- Targets
- -
- Full type
- ToggleGroupValue
defaultValue ToggleGroupValue -
- Description
- Sets the initial ToggleGroup value for uncontrolled usage.
- Kind
- control
- Targets
- -
- Full type
- ToggleGroupValue
disabled boolean false
- Description
- Disables the Root part.
- Kind
- option
- Targets
- -
- Full type
- boolean
loopFocus boolean true
- Description
- Lets keyboard focus wrap around the ToggleGroup items.
- Kind
- option
- Targets
- -
- Full type
- boolean
multiple boolean false
- Description
- Allows multiple ToggleGroup values to be selected.
- Kind
- option
- Targets
- -
- Full type
- boolean
orientation "horizontal" | "vertical" "horizontal"
- Description
- Sets the ToggleGroup orientation.
- Kind
- option
- Targets
- -
- Full type
- "horizontal" | "vertical"
onValueChange (value: ToggleGroupValue, details: ToggleGroupValueChangeDetails) => void -
- Description
- Runs when the ToggleGroup value changes.
- Kind
- callback
- Targets
- -
- Full type
- (value: ToggleGroupValue, details: ToggleGroupValueChangeDetails) => void
Events
Event Callback Value Toggle
valueChange onValueChange value: ToggleGroupValue
- Description
- Fires when the value changes for ToggleGroup.
- DOM event
- starwind:value-change
- Details type
- ToggleGroupValueChangeDetails
- Timing
- -
- Cancelable
- No
State
State Type Props Toggle
value ToggleGroupValue value / defaultValue
- Description
- Tracks the current ToggleGroup value.
- Initial attribute
- data-default-value
- Runtime getter
- getValue
- Runtime setter
- setValue
- State control support
- React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-default-value, emits starwind:value-change, and updates with setValue. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state.
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 ToggleGroup value from Runtime code.
setDisabled prop: disabled Updates whether ToggleGroup is disabled from Runtime code.
setLoopFocus prop: loopFocus Updates ToggleGroup keyboard focus wrapping from Runtime code.
setMultiple prop: multiple Updates whether ToggleGroup allows multiple values from Runtime code.
setOrientation prop: orientation Updates the ToggleGroup orientation from Runtime code.
Related Styled Components
Component Relationship
Toggle Group Composite