React Native Button Multiselect

React Native Button Multiselect is a versatile component designed for seamless integration of button-based multi-select functionality into React Native applications.

Table of Contents

1. Demo
2. Installation
3. Usage
4. Props
5. Button Layout

Installation

Install the package using Yarn or npm:

yarn add react-native-button-multiselect
# or
npm install --save react-native-button-multiselect

Try it out

To experiment with an example app using Expo:

1. Clone this repository.
2. Navigate to the example folder.
3. Install dependencies:

cd example
yarn install

Now, you can run the app with

yarn start

Basic Usage

Implement the component in your app:

import ButtonMultiselect, {
  ButtonLayout,
} from 'react-native-button-multiselect';

// ...

const App = () => {
  // Define your button options
  const buttons = [
    { label: 'Option 1', value: 'option1' },
    { label: 'Option 2', value: 'option2' },
  ];

  // Set up state and handlers for selected buttons
  const [selectedButtons, setSelectedButtons] = useState([]);

  const handleButtonSelected = (selectedValues) => {
    setSelectedButtons(selectedValues);
  };

  return (
    <ButtonMultiselect
      layout={ButtonLayout.CAROUSEL} // Choose from ButtonLayout enum: CAROUSEL, FULL_WIDTH, GRID
      buttons={buttons}
      selectedButtons={selectedButtons}
      onButtonSelected={handleButtonSelected}
      // Additional props can be customized as needed
    />
  );
};

export default App;

Props

Detailed descriptions of the available props:

Prop	Type	Description	Required
layout	ButtonLayout	Layout type for rendering buttons: ButtonLayout.CAROUSEL, ButtonLayout.FULL_WIDTH, or ButtonLayout.GRID.	Yes
buttons	ButtonProps[]	Array of button options, each with a label and unique value. Details	Yes
selectedButtons	string | string[]	Currently selected button(s). Use an array for multi-select mode, and a string for single-select mode.	Yes
onButtonSelected	Function	Callback function invoked when a button is selected. Receives the selected value(s).	Yes
containerStyle	ViewStyle | Array<ViewStyle>	Custom styles for the container wrapping the buttons.	No
horizontalPadding	number	Horizontal padding for the buttons.	No
buttonStyle	ViewStyle | Array<ViewStyle>	Custom styles for the buttons.	No
textStyle	TextStyle | Array<TextStyle>	Custom styles for the button text.	No
selectedColors	ThemeColors	Theme colors for selected buttons, including backgroundColor, textColor, and borderColor. Details	No
unselectedColors	ThemeColors	Theme colors for unselected buttons, including backgroundColor, textColor, and borderColor. Details	No
buttonMargin	number	Margin between buttons.	No
multiselect	boolean	Enable multi-select mode. Default is false (single-select). Details	No

ButtonProps

Prop	Type	Description
label	string	Label for the button.
value	string	Unique value for the button.

ThemeColors

Prop	Type	Description
backgroundColor	string	Button's background.
textColor	string	Button's text color.
borderColor	string	Button's border.

Conditional Props (multiselect)

Condition	Props	Description
multiselect:true	{ selectedButtons: string[]; onButtonSelected: (value: string[]) => void; }	Conditional prop for multi-select mode. Requires selectedButtons as an array and the onButtonSelected callback function that will return an array of strings.
multiselect:false	{ selectedButtons: string; onButtonSelected: (value: string) => void; }	Conditional prop for single-select mode. Requires selectedButtons as a string and the onButtonSelected callback function that will return a string.

Button Layout

FULL_WIDTH

<ButtonMultiselect
  buttons={[]}
  layout={ButtonLayout.FULL_WIDTH}
  onButtonSelected={setSelectedOption}
  selectedButtons={selectedOption}
/>

CAROUSEL

<ButtonMultiselect
  buttons={[]}
  layout={ButtonLayout.CAROUSEL}
  onButtonSelected={setSelectedOption}
  selectedButtons={selectedOption}
/>

GRID

<ButtonMultiselect
  buttons={[]}
  layout={ButtonLayout.GRID}
  onButtonSelected={setSelectedOption}
  selectedButtons={selectedOption}
/>

Multiselect

Single-select mode (like radio)

<ButtonMultiselect
  buttons={[...]}
  layout={ButtonLayout.GRID}
  onButtonSelected={setSelectedOption}
  selectedButtons={selectedOption}
/>

Multi-select (like checkbox)

<ButtonMultiselect
  buttons={[...]}
  multiselect
  layout={ButtonLayout.CAROUSEL}
  onButtonSelected={setSelectedOptions}
  selectedButtons={selectedOptions}
/>

License

This project is licensed under the MIT License. See the License tab for more details.

---