React Native Bouncy Checkbox Group

A fully customizable, animated checkbox group component for React Native applications.

Features

• Single and multiple selection support
• "Always selected" mode to ensure one option is always chosen
• Horizontal and vertical layouts
• Customizable animations and spacing
• TypeScript support
• Flexible styling options
• Bouncy animation effects

Installation

1npm install react-native-bouncy-checkbox-group
2# or
3yarn add react-native-bouncy-checkbox-group

This package requires react-native-bouncy-checkbox version 4.1.2 or higher. If you haven't installed it yet:

1npm install react-native-bouncy-checkbox@latest
2# or
3yarn add react-native-bouncy-checkbox@latest

Usage

Basic Usage

1import BouncyCheckboxGroup, { CheckboxItem } from 'react-native-bouncy-checkbox-group';
2
3const data = [
4  {
5    id: 0,
6    text: 'Option 1',
7    fillColor: '#ff7473',
8    unfillColor: '#fbbfbb',
9  },
10  {
11    id: 1,
12    text: 'Option 2',
13    fillColor: '#5567e9',
14    unfillColor: '#afb5f5',
15  },
16];
17
18// Inside your component
19<BouncyCheckboxGroup
20  data={data}
21  onChange={(selectedItem) => {
22    console.log('Selected:', selectedItem);
23  }}
24/>

Single Selection with Initial Value

1<BouncyCheckboxGroup
2  data={data}
3  initial={0} // Set initial selection to item with id=0
4  spacing={8} // Add spacing between items
5  onChange={(selectedItem) => {
6    console.log('Selected:', selectedItem);
7  }}
8/>

Always Selected Mode

The alwaysSelect feature ensures that one checkbox must always be selected in single selection mode. This is useful for cases where having no selection is not a valid state, like radio button groups.

1<BouncyCheckboxGroup
2  data={data}
3  initial={0} // Set initial selection
4  alwaysSelect={true} // Prevent deselection of the selected item
5  onChange={(selectedItem) => {
6    console.log('Selected:', selectedItem);
7  }}
8/>

With alwaysSelect enabled:

• One checkbox is always selected
• Users can change selection by tapping a different checkbox
• Attempting to deselect the currently selected checkbox has no effect
• If no initial value is set, the first item is automatically selected

Multiple Selection

Enable choosing multiple options simultaneously:

1<BouncyCheckboxGroup
2  data={data}
3  multiple={true} // Enable multiple selection
4  initial={[0, 2]} // Optional initial selections
5  onChange={(selectedItems) => {
6    console.log('Selected:', selectedItems);
7  }}
8/>

Vertical Layout

Change the orientation to vertical:

1<BouncyCheckboxGroup
2  data={data}
3  style={{ flexDirection: 'column' }}
4  onChange={(selectedItem) => {
5    console.log('Selected:', selectedItem);
6  }}
7/>

Customizing Animation and Spacing

1<BouncyCheckboxGroup
2  data={data}
3  animationDuration={100} // Faster animation (default: 300ms)
4  spacing={12} // Add 12 pixels between checkboxes
5  onChange={(selectedItem) => {
6    console.log('Selected:', selectedItem);
7  }}
8/>

Custom Styling for Individual Checkboxes

The data array accepts all properties from the react-native-bouncy-checkbox package:

1const customData = [
2  {
3    id: 0,
4    text: 'Custom Option',
5    fillColor: '#ff7473',
6    unfillColor: '#ffffff',
7    textStyle: { 
8      textDecorationLine: 'none', 
9      fontSize: 16,
10      color: '#333'
11    },
12    iconStyle: { 
13      borderRadius: 8,
14      borderColor: '#ff7473'
15    },
16    size: 24
17  },
18  // More items...
19];

Using External State Management

If you need to control the checkbox state from outside, you can use the useBuiltInState prop in your checkbox items:

1const [myState, setMyState] = useState(false);
2
3const customData = [
4  {
5    id: 0,
6    text: 'Externally Controlled',
7    isChecked: myState,
8    useBuiltInState: false, // Disable internal state management
9    onPress: (checked) => {
10      setMyState(!myState); // Update your own state
11    }
12  },
13  // More items...
14];

Props

BouncyCheckboxGroup Props

Prop	Type	Default	Description
data	CheckboxItem[]	Required	Array of checkbox items
onChange	(selectedItem: CheckboxItem | CheckboxItem[]) => void	Required	Callback when selection changes
style	StyleProp<ViewStyle>	undefined	Container style
initial	SelectionID | SelectionID[]	undefined	Initial selected item(s) by ID
multiple	boolean	false	Enable multiple selection
alwaysSelect	boolean	false	Ensures one checkbox is always selected (single select mode only)
animationDuration	number	300	Duration of bounce animation in ms
spacing	number	0	Spacing between checkbox items
itemContainerStyle	StyleProp<ViewStyle>	undefined	Style for each checkbox container
checkboxProps	BouncyCheckboxProps	undefined	Props applied to all checkboxes

CheckboxItem Props

The CheckboxItem interface extends all props from react-native-bouncy-checkbox with an added required id field:

Prop	Type	Default	Description
id	string | number	Required	Unique identifier for the checkbox
text	string	undefined	Text label for the checkbox
isChecked	boolean	undefined	Control the checked state externally
useBuiltInState	boolean	true	Set to false to manually control checkbox state
fillColor	string	#f09f48	Color when checked
unfillColor	string	transparent	Color when unchecked
textStyle	StyleProp<TextStyle>	Default	Style for the text label
iconStyle	StyleProp<ViewStyle>	Default	Style for the checkbox icon
...	...	...	All other props from BouncyCheckbox

Example

Check out the example folder for a fully working demo app that demonstrates all features.

License

MIT