https://github.com/wrathchaos/react-native-bouncy-checkbox-group
Fully customizable bouncy checkbox group for React Native
https://github.com/wrathchaos/react-native-bouncy-checkbox-group
apple checkbox checkbox-group development ios javascript mobile mobile-app mobile-application-development programming react react-native react-native-checkbox react-native-checkbox-group reactjs typescript
Last synced: 4 months ago
JSON representation
Fully customizable bouncy checkbox group for React Native
- Host: GitHub
- URL: https://github.com/wrathchaos/react-native-bouncy-checkbox-group
- Owner: WrathChaos
- License: mit
- Created: 2021-10-08T14:42:38.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2024-04-19T14:03:42.000Z (over 1 year ago)
- Last Synced: 2025-04-18T09:02:25.374Z (6 months ago)
- Topics: apple, checkbox, checkbox-group, development, ios, javascript, mobile, mobile-app, mobile-application-development, programming, react, react-native, react-native-checkbox, react-native-checkbox-group, reactjs, typescript
- Language: TypeScript
- Homepage: https://freakycoder.com/
- Size: 4.64 MB
- Stars: 27
- Watchers: 2
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# React Native Bouncy Checkbox Group
A fully customizable, animated checkbox group component for React Native applications.
## 🎉 Version 2.0.0 Now Available!
We're excited to announce the release of version 2.0.0 with several new features and improvements:
- **Multiple Selection Mode**: Now supports selecting multiple checkboxes with the `multiple` prop
- **Always Select Mode**: Ensures one checkbox is always selected with the `alwaysSelect` prop
- **Improved Type Support**: Better TypeScript definitions and support for both string and numeric IDs
- **Animation Control**: Customize animation duration with the `animationDuration` prop
- **Flexible Spacing**: Control spacing between checkboxes with the `spacing` prop
[See full release notes](https://github.com/WrathChaos/react-native-bouncy-checkbox-group/releases/tag/v2.0.0)
## 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
```bash
npm install react-native-bouncy-checkbox-group
# or
yarn 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:
```bash
npm install react-native-bouncy-checkbox@latest
# or
yarn add react-native-bouncy-checkbox@latest
```
## Usage
### Basic Usage
```jsx
import BouncyCheckboxGroup, { CheckboxItem } from 'react-native-bouncy-checkbox-group';
const data = [
{
id: 0,
text: 'Option 1',
fillColor: '#ff7473',
unfillColor: '#fbbfbb',
},
{
id: 1,
text: 'Option 2',
fillColor: '#5567e9',
unfillColor: '#afb5f5',
},
];
// Inside your component
{
console.log('Selected:', selectedItem);
}}
/>
```
### Single Selection with Initial Value
```jsx
{
console.log('Selected:', selectedItem);
}}
/>
```
### 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.
```jsx
{
console.log('Selected:', selectedItem);
}}
/>
```
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:
```jsx
{
console.log('Selected:', selectedItems);
}}
/>
```
### Vertical Layout
Change the orientation to vertical:
```jsx
{
console.log('Selected:', selectedItem);
}}
/>
```
### Customizing Animation and Spacing
```jsx
{
console.log('Selected:', selectedItem);
}}
/>
```
### Custom Styling for Individual Checkboxes
The `data` array accepts all properties from the `react-native-bouncy-checkbox` package:
```jsx
const customData = [
{
id: 0,
text: 'Custom Option',
fillColor: '#ff7473',
unfillColor: '#ffffff',
textStyle: {
textDecorationLine: 'none',
fontSize: 16,
color: '#333'
},
iconStyle: {
borderRadius: 8,
borderColor: '#ff7473'
},
size: 24
},
];
```
### Using External State Management
If you need to control the checkbox state from outside, you can use the `useBuiltInState` prop in your checkbox items:
```jsx
const [myState, setMyState] = useState(false);
const customData = [
{
id: 0,
text: 'Externally Controlled',
isChecked: myState,
useBuiltInState: false, // Disable internal state management
onPress: (checked) => {
setMyState(!myState); // Update your own state
}
},
// More items...
];
```
### Resetting Selection
You can programmatically reset checkbox selection by managing state externally:
```jsx
const [selectedId, setSelectedId] = useState(0); // Start with initial selection
// Reset function
const resetSelection = () => {
setSelectedId(null); // Set to null to clear selection
};
// In your component
return (
<>
{
// If you want default behavior (clicking selected item deselects it)
// just use alwaysSelect={false} (the default)
// For programmatic control:
setSelectedId(selectedItem.id);
}}
/>
>
);
```
> Note: By default (`alwaysSelect={false}`), clicking an already selected checkbox will deselect it. Use `alwaysSelect={true}` for radio button behavior where one checkbox must always be selected.
## 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` | `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` | `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` | Default | Style for the text label |
| `iconStyle` | `StyleProp` | 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