React-native-button-multiselect NPM

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.

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:

Clone this repository.
Navigate to the example folder.
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}
/>