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.