Toggle Group

Coordinate multiple toggles with single or multiple selection modes, perfect for toolbars and button groups.

Installation

npm install @native-ui-org/primitives

pnpm add @native-ui-org/primitives

yarn add @native-ui-org/primitives

bun add @native-ui-org/primitives

Overview

ToggleGroup manages multiple toggle buttons as a coordinated group with flexible selection modes.

Feature	Description	Platforms
ToggleGroup	Root container managing toggle states	iOS, Android, Web

Setup & Usage Guide

ToggleGroup provides coordinated state for multiple toggle buttons.

1. Install and Import

Install from npm:

npm install @native-ui-org/primitives

Then import from the package:

import { 
  ToggleGroup, 
  Toggle 
} from "@native-ui-org/primitives";

2. Single Selection Mode

Only one toggle can be pressed at a time:

<ToggleGroup type="single" defaultValue="left">
  <Toggle value="left">
    {({ pressed }) => (
      <View style={pressed && styles.active}>
        <Icon name="align-left" />
      </View>
    )}
  </Toggle>
  
  <Toggle value="center">
    {({ pressed }) => (
      <View style={pressed && styles.active}>
        <Icon name="align-center" />
      </View>
    )}
  </Toggle>
  
  <Toggle value="right">
    {({ pressed }) => (
      <View style={pressed && styles.active}>
        <Icon name="align-right" />
      </View>
    )}
  </Toggle>
</ToggleGroup>

3. Multiple Selection Mode

Allow multiple toggles to be pressed simultaneously:

<ToggleGroup type="multiple" defaultValue={["bold", "italic"]}>
    <Toggle value="bold">
    {({ pressed }) => (
      <View style={pressed && styles.active}>
        <Icon name="bold" />
      </View>
    )}
    </Toggle>
    
    <Toggle value="italic">
    {({ pressed }) => (
      <View style={pressed && styles.active}>
        <Icon name="italic" />
      </View>
    )}
    </Toggle>
    
    <Toggle value="underline">
    {({ pressed }) => (
      <View style={pressed && styles.active}>
        <Icon name="underline" />
      </View>
    )}
    </Toggle>
</ToggleGroup>

4. Controlled State

const [alignment, setAlignment] = useState("left");

<ToggleGroup type="single" value={alignment} onValueChange={setAlignment}>
  <Toggle value="left">{({ pressed }) => /* ... */}</Toggle>
  <Toggle value="center">{({ pressed }) => /* ... */}</Toggle>
  <Toggle value="right">{({ pressed }) => /* ... */}</Toggle>
</ToggleGroup>

5. Disabled Group

<ToggleGroup disabled type="single">
  <Toggle value="option1">{({ pressed }) => /* ... */}</Toggle>
  <Toggle value="option2">{({ pressed }) => /* ... */}</Toggle>
</ToggleGroup>

API Reference

ToggleGroup

Container coordinating multiple toggles.

Prop	Type	Default	Description
`type`	`"single" \| "multiple"`	—	Required. Selection mode
`value`	`string \| string[]`	—	Controlled value(s)
`defaultValue`	`string \| string[]`	—	Initial value(s) (uncontrolled)
`onValueChange`	`(value: string \| string[]) => void`	—	Callback when selection changes
`disabled`	boolean	`false`	Disable all toggles
`rovingFocus`	boolean	`true`	Enable keyboard navigation (web)

Note: Individual toggles use their value prop to identify themselves.

Platform Behavior

Platform	Implementation	Characteristics
iOS / Android	Context-based state coordination	Native touch feedback
Web	Button group with ARIA roles	Keyboard navigation support
All Platforms	Consistent API	Same props, same behavior

Accessibility

Web:

role="group" on container
aria-pressed on each toggle
Keyboard navigation (arrows, Space/Enter)
Focus management

Mobile:

Group announced by screen readers
Individual toggle states accessible

Version History

Version	Notes
`0.1.0`	Initial release — toggle group with single/multiple modes and state management.

Summary: ToggleGroup coordinates multiple toggle buttons with flexible selection modes. Use single mode for mutually exclusive options (alignment, size, etc.). Use multiple mode for independent formatting options (bold, italic, underline). Perfect for toolbars, button groups, and formatting controls.