Skip to content

WrathChaos/react-native-bouncy-checkbox-group

Repository files navigation

React Native Bouncy Checkbox Group

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

react-native-bouncy-checkbox-group.gif

🎉 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

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

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:

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

Usage

Basic Usage

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
<BouncyCheckboxGroup
  data={data}
  onChange={(selectedItem) => {
    console.log('Selected:', selectedItem);
  }}
/>

Single Selection with Initial Value

<BouncyCheckboxGroup
  data={data}
  initial={0} // Set initial selection to item with id=0
  spacing={8} // Add spacing between items
  onChange={(selectedItem) => {
    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.

<BouncyCheckboxGroup
  data={data}
  initial={0} // Set initial selection
  alwaysSelect={true} // Prevent deselection of the selected item
  onChange={(selectedItem) => {
    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:

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

Vertical Layout

Change the orientation to vertical:

<BouncyCheckboxGroup
  data={data}
  style={{ flexDirection: 'column' }}
  onChange={(selectedItem) => {
    console.log('Selected:', selectedItem);
  }}
/>

Customizing Animation and Spacing

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

Custom Styling for Individual Checkboxes

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

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:

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:

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 (
  <>
    <BouncyCheckboxGroup
      data={checkboxData}
      initial={selectedId}
      onChange={(selectedItem) => {
        // If you want default behavior (clicking selected item deselects it)
        // just use alwaysSelect={false} (the default)
        
        // For programmatic control:
        setSelectedId(selectedItem.id);
      }}
    />
    <Button title="Reset Selection" onPress={resetSelection} />
  </>
);

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

PropTypeDefaultDescription
dataCheckboxItem[]RequiredArray of checkbox items
onChange(selectedItem: CheckboxItem | CheckboxItem[]) => voidRequiredCallback when selection changes
styleStyleProp<ViewStyle>undefinedContainer style
initialSelectionID | SelectionID[]undefinedInitial selected item(s) by ID
multiplebooleanfalseEnable multiple selection
alwaysSelectbooleanfalseEnsures one checkbox is always selected (single select mode only)
animationDurationnumber300Duration of bounce animation in ms
spacingnumber0Spacing between checkbox items
itemContainerStyleStyleProp<ViewStyle>undefinedStyle for each checkbox container
checkboxPropsBouncyCheckboxPropsundefinedProps applied to all checkboxes

CheckboxItem Props

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

PropTypeDefaultDescription
idstring | numberRequiredUnique identifier for the checkbox
textstringundefinedText label for the checkbox
isCheckedbooleanundefinedControl the checked state externally
useBuiltInStatebooleantrueSet to false to manually control checkbox state
fillColorstring#f09f48Color when checked
unfillColorstringtransparentColor when unchecked
textStyleStyleProp<TextStyle>DefaultStyle for the text label
iconStyleStyleProp<ViewStyle>DefaultStyle 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