Switch Group

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

SwitchGroup manages multiple switches as a coordinated group with record-based state.

Feature	Description	Platforms
SwitchGroup	Root container coordinating switches	iOS, Android, Web

Setup & Usage Guide

SwitchGroup simplifies managing multiple toggle switches together.

1. Install and Import

Install from npm:

npm install @native-ui-org/primitives

Then import from the package:

import { 
  SwitchGroup, 
  Switch 
} from "@native-ui-org/primitives";

2. Basic Usage

Manage multiple switches as a group:

<SwitchGroup defaultValue={{ notifications: true, darkMode: false }}>
  <View style={styles.row}>
    <Text>Notifications</Text>
    <Switch name="notifications">
      {({ checked }) => (
        <View style={checked ? styles.on : styles.off}>
          <View style={styles.thumb} />
        </View>
      )}
    </Switch>
  </View>
  
  <View style={styles.row}>
    <Text>Dark Mode</Text>
    <Switch name="darkMode">
      {({ checked }) => (
        <View style={checked ? styles.on : styles.off}>
          <View style={styles.thumb} />
        </View>
      )}
    </Switch>
  </View>
</SwitchGroup>

3. Controlled State

Manage group state externally:

const [settings, setSettings] = useState({
  notifications: true,
  darkMode: false,
  autoSave: true,
});

<SwitchGroup value={settings} onValueChange={setSettings}>
  <Switch name="notifications">
    {({ checked }) => /* ... */}
  </Switch>
  <Switch name="darkMode">
    {({ checked }) => /* ... */}
  </Switch>
  <Switch name="autoSave">
    {({ checked }) => /* ... */}
  </Switch>
</SwitchGroup>

4. Disabled Group

Disable all switches at once:

<SwitchGroup disabled>
  <Switch name="option1">{({ checked }) => /* ... */}</Switch>
  <Switch name="option2">{({ checked }) => /* ... */}</Switch>
</SwitchGroup>

API Reference

SwitchGroup

Container coordinating multiple switches.

Prop	Type	Default	Description
`value`	`Record<string, boolean>`	—	Controlled state values
`defaultValue`	`Record<string, boolean>`	`{}`	Initial state (uncontrolled)
`onValueChange`	`(value: Record<string, boolean>) => void`	—	Callback when any switch changes
`disabled`	boolean	`false`	Disable all switches
`asChild`	boolean	`false`	Use Slot pattern

Note: Individual switches use their name prop to identify themselves in the group state.

Platform Behavior

Platform	Implementation	Characteristics
iOS / Android	Context-based state coordination	Native performance
Web	Fieldset with switches	Form compatible
All Platforms	Consistent API	Same props, same behavior

Accessibility

Web:

Semantic grouping with fieldset
Individual switches properly labeled
Keyboard navigation

Mobile:

Group announced by screen readers
Individual switch states accessible

Version History

Version	Notes
`0.1.0`	Initial release — switch group with record-based state management.

Summary: SwitchGroup simplifies managing multiple toggle switches. Use it for settings panels, feature flags, or grouped boolean controls. Provides coordinated state management with record-based values.