Checkbox
Create accessible checkboxes with custom styling and full keyboard support across all platforms.
Preview
Interactive Demo
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
Checkbox is a compound component for building checkboxes with labels and custom indicators.
| Feature | Description | Platforms |
|---|---|---|
| Checkbox | Root container managing state | iOS, Android, Web |
| CheckboxIndicator | Visual checkbox state indicator | iOS, Android, Web |
| CheckboxLabel | Clickable label text | iOS, Android, Web |
Setup & Usage Guide
Checkbox provides the structure for accessible checkbox inputs with full control over styling.
1. Install and Import
Install from npm:
npm install @native-ui-org/primitivesThen import from the package:
import {
Checkbox,
CheckboxIndicator,
CheckboxLabel
} from "@native-ui-org/primitives";2. Basic Usage
Simple checkbox with label:
<Checkbox defaultChecked={false}>
<CheckboxIndicator>
{({ checked }) => (
<View style={checked ? styles.checked : styles.unchecked}>
{checked && <Icon name="check" />}
</View>
)}
</CheckboxIndicator>
<CheckboxLabel>
<Text>Accept terms and conditions</Text>
</CheckboxLabel>
</Checkbox>3. Controlled State
Manage checkbox state externally:
const [checked, setChecked] = useState(false);
<Checkbox checked={checked} onCheckedChange={setChecked}>
<CheckboxIndicator>
{({ checked }) => (
<View style={styles.indicator}>
{checked && <Text>✓</Text>}
</View>
)}
</CheckboxIndicator>
<CheckboxLabel>
<Text>Subscribe to newsletter</Text>
</CheckboxLabel>
</Checkbox>4. Disabled State
<Checkbox disabled checked={true}>
<CheckboxIndicator>
{({ checked }) => (
<View style={styles.indicatorDisabled}>
{checked && <Icon name="check" color="#ccc" />}
</View>
)}
</CheckboxIndicator>
<CheckboxLabel>
<Text style={styles.labelDisabled}>Disabled option</Text>
</CheckboxLabel>
</Checkbox>API Reference
Checkbox
Root container managing checkbox state.
| Prop | Type | Default | Description |
|---|---|---|---|
checked | boolean | — | Controlled checked state |
defaultChecked | boolean | false | Initial state (uncontrolled) |
onCheckedChange | (checked: boolean) => void | — | Callback when state changes |
disabled | boolean | false | Disable interactions |
required | boolean | false | Mark as required (forms) |
name | string | — | Form field name |
value | string | "on" | Form value when checked |
asChild | boolean | false | Use Slot pattern |
CheckboxIndicator
Visual indicator for checkbox state.
| Prop | Type | Default | Description |
|---|---|---|---|
children | function | React.ReactNode | — | Render function or content |
forceMount | boolean | false | Keep mounted when unchecked |
asChild | boolean | false | Use Slot pattern |
CheckboxLabel
Clickable label text.
| Prop | Type | Default | Description |
|---|---|---|---|
asChild | boolean | false | Use Slot pattern |
...props | any | — | Standard Text props |
Platform Behavior
| Platform | Implementation | Characteristics |
|---|---|---|
| iOS / Android | Pressable with state | Native touch feedback |
| Web | Input checkbox (hidden) + visual | Keyboard accessible, form compatible |
| All Platforms | Consistent API | Same props, same behavior |
Accessibility
Web:
- Hidden
<input type="checkbox">for form compatibility - Proper
labelassociation - Keyboard support (Space to toggle)
- Focus management
Mobile:
- Accessibility role "checkbox"
- State announced to screen readers
- Works with VoiceOver and TalkBack
Version History
| Version | Notes |
|---|---|
0.1.0 | Initial release — checkbox with label and indicator, controlled/uncontrolled states. |
Summary: Checkbox provides accessible checkbox inputs with full styling control. Use it for forms, settings, multi-select lists, or any boolean input. Supports both controlled and uncontrolled modes with proper accessibility.