Checkbox

The Checkbox component allows users to select or deselect an option. It supports various sizes, colors, custom icons, and can be controlled or uncontrolled.

Installation

$ cbui-cli install @crossbuildui/checkbox

Import

index.tsx
1import { Checkbox } from '@/crossbuildui/checkbox'; 2// import Icon from 'react-native-vector-icons/MaterialIcons'; // Or your preferred icon library for custom icons

Checkbox Component

Basic Usage

Provide children for the label and optionally a color. Use defaultSelected for initial uncontrolled state.

MyComponent.tsx
1<View style={{gap: 8}}> 2 <Checkbox defaultSelected color="primary"> 3 Primary Checkbox 4 </Checkbox> 5 <Checkbox color="secondary"> 6 Secondary Checkbox (Uncontrolled) 7 </Checkbox> 8</View>

Sizes

Adjust checkbox size with sm, md (default), or lg.

MyComponent.tsx
1<View style={{flexDirection: 'row', alignItems: 'center', gap: 16}}> 2 <Checkbox defaultSelected color="success" size="sm">Small</Checkbox> 3 <Checkbox defaultSelected color="success" size="md">Medium (Default)</Checkbox> 4 <Checkbox defaultSelected color="success" size="lg">Large</Checkbox> 5</View>

Colors

Set the color theme using the color prop. Supported colors include primary (default), secondary, success, warning, danger, and default.

MyComponent.tsx
1<View style={{flexDirection: 'column', gap: 8}}> 2 <Checkbox defaultSelected color="primary">Primary</Checkbox> 3 <Checkbox defaultSelected color="secondary">Secondary</Checkbox> 4 <Checkbox defaultSelected color="success">Success</Checkbox> 5 <Checkbox defaultSelected color="warning">Warning</Checkbox> 6 <Checkbox defaultSelected color="danger">Danger</Checkbox> 7 <Checkbox defaultSelected color="default">Default</Checkbox> 8</View>

Radius

Control the border radius of the checkbox square with none, sm (default), md, lg, or full.

MyComponent.tsx
1<View style={{flexDirection: 'row', flexWrap: 'wrap', alignItems: 'center', gap: 16}}> 2 <Checkbox defaultSelected color="warning" radius="none">None</Checkbox> 3 <Checkbox defaultSelected color="warning" radius="sm">Small (Default)</Checkbox> 4 <Checkbox defaultSelected color="warning" radius="md">Medium</Checkbox> 5 <Checkbox defaultSelected color="warning" radius="lg">Large</Checkbox> 6 <Checkbox defaultSelected color="warning" radius="full">Full</Checkbox> 7</View>

Line Through Label

If lineThrough is true, the label text will have a line-through style when the checkbox is selected.

MyComponent.tsx
1<Checkbox defaultSelected color="primary" lineThrough> 2 Option with line-through 3</Checkbox>

With Custom Icon

Provide a custom React element to the icon prop to replace the default checkmark.

MyComponent.tsx
1// Example using a Icon component from react-native-vector-icons 2import Icon from 'react-native-vector-icons/MaterialCommunityIcons'; 3 4<View style={{gap: 8}}> 5 <Checkbox 6 defaultSelected 7 color="danger" 8 icon={<Icon name="heart" size={16} color="white" />} 9 > 10 Custom Heart Icon 11 </Checkbox> 12 <Checkbox 13 defaultSelected 14 color="success" 15 size="lg" 16 icon={<Icon name="star" size={20} color="white" />} 17 > 18 Large Custom Star Icon 19 </Checkbox> 20</View>

Controlled and Uncontrolled

Manage selection state externally using isSelected and onChange for a controlled component, or use defaultSelected for an uncontrolled component.

MyComponent.tsx
1import React, { useState } from 'react'; 2import { View, Text } from 'react-native'; 3import { Checkbox } from '@crossbuildui/checkbox'; 4 5function MyControlledCheckbox() { 6 const [selected, setSelected] = React.useState(true); 7 8 return ( 9 <View style={{gap: 8}}> 10 <Checkbox 11 isSelected={selected} 12 onChange={setSelected} 13 color="primary" 14 > 15 Controlled Checkbox 16 </Checkbox> 17 <Text>Current state: {selected ? 'Selected' : 'Not Selected'}</Text> 18 19 <Checkbox defaultSelected color="secondary"> 20 Uncontrolled (uses defaultSelected) 21 </Checkbox> 22 </View> 23 ); 24} 25 26// To use: <MyControlledCheckbox /> 27

Read-Only and Disabled

Use isReadOnly to prevent user interaction while maintaining focusability, or disabled to make it non-interactive and visually distinct.

MyComponent.tsx
1<View style={{flexDirection: 'row', flexWrap: 'wrap', gap: 16}}> 2 <Checkbox defaultSelected color="primary" isReadOnly> 3 Read-Only (Selected) 4 </Checkbox> 5 <Checkbox color="secondary" isReadOnly> 6 Read-Only (Unselected) 7 </Checkbox> 8 <Checkbox defaultSelected color="primary" disabled> 9 Disabled (Selected) 10 </Checkbox> 11 <Checkbox color="secondary" disabled> 12 Disabled (Unselected) 13 </Checkbox> 14</View>

Disable Animation

Set disableAnimation= to turn off the check/uncheck animations.

MyComponent.tsx
1<Checkbox defaultSelected color="primary" disableAnimation> 2 Animation Disabled 3</Checkbox>

Form-related Props

Use value and name for integration with form libraries or custom form handling. isRequired semantically marks the checkbox as required.

MyComponent.tsx
1<View style={{gap: 8}}> 2 <Checkbox value="newsletter" name="subscription_prefs" color="primary"> 3 Subscribe to newsletter 4 </Checkbox> 5 <Checkbox value="terms_agree" name="agreement_status" color="secondary" isRequired> 6 Agree to terms (Required) 7 </Checkbox> 8</View> 9{/* 10 'value' and 'name' are typically used with form libraries or for custom form handling. 11 'isRequired' is a semantic prop; visual indication (e.g., an asterisk) 12 would usually be handled separately in the label or form layout. 13*/}

Props Overview

PROPTYPEDEFAULTDESCRIPTION
childrenReactNode-The label content for the checkbox.
iconReactElement-Custom icon element for the selected state. Overrides default checkmark.
valuestring-The value associated with the checkbox, used in forms.
namestring-The name attribute for the checkbox, used in forms.
size'sm' | 'md' | 'lg''md'Size of the checkbox.
colorCheckboxColor'primary'Color theme of the checkbox.
radius'none' | 'sm' | 'md' | 'lg' | 'full''sm'Border radius of the checkbox.
lineThroughbooleanfalseIf true, label text has line-through when selected.
isSelectedboolean-Controlled selected state. Use with onChange.
defaultSelectedbooleanfalseInitial selected state for uncontrolled checkbox.
isRequiredbooleanfalseMarks checkbox as required in forms (semantic).
isReadOnlybooleanfalseIf true, selection cannot be changed by user.
disabledbooleanfalseIf true, checkbox is disabled and non-interactive.
disableAnimationbooleanfalseIf true, check/uncheck animations are disabled.
stylesCheckboxSlotsStyles-Custom styles for slots: wrapper, checkbox, label, icon.
styleStyleProp<ViewStyle>-Custom style for the root Pressable wrapper. Overrides styles.wrapper.
onChange(isSelected: boolean) => void-Callback fired when the checkbox's selected state changes.
...PressablePropsvarious-Other props from React Native's Pressable component.

Styling

Customize the Checkbox appearance using the style prop for the main wrapper or the styles prop for more granular control over internal slots:

  • style: Applied to the root Pressable component that wraps the checkbox and label.
  • styles.wrapper: Style for the main wrapper (merged with and can be overridden by the main style prop).
  • styles.checkbox: Style for the visible checkbox box container.
  • styles.label: Style for the label Text component.
  • styles.icon: Style for the View container that wraps the icon element when the checkbox is selected.
MyComponent.tsx
1<Checkbox 2 defaultSelected 3 color="primary" 4 style={{ paddingVertical: 16, backgroundColor: '#e0e7ff', borderRadius: 8 }} // Wrapper Pressable style 5 styles={{ 6 checkbox: { borderWidth: 3, borderColor: 'darkblue', backgroundColor: '#a7bfff' }, 7 label: { color: 'purple', fontWeight: 'bold', marginLeft: 16, fontStyle: 'italic' }, 8 icon: { transform: [{ rotate: '10deg' }] } // Style for the container of the icon 9 }} 10> 11 Custom Styled Checkbox 12</Checkbox>

Accessibility

The Checkbox component is built on Pressable and includes accessibility features:

  • accessibilityRole="checkbox" is set by default.
  • accessibilityState includes { checked: isSelected, disabled: disabled }.
  • An accessibilityLabel is automatically derived from string children, or defaults to 'Checkbox'. Provide a custom accessibilityLabel if children are not descriptive or are complex React nodes.
Button Input