nim-react-dropdown/README.md

A customizable and animated dropdown component for React Native

# nim-react-dropdown

`nim-react-dropdown` is a customizable and animated dropdown component for React Native. It provides smooth animations, supports multi-selection, search functionality, custom styling, and more advanced features, making it perfect for modern mobile apps.

## Features

- **Smooth Animations**: Smooth transition when opening and closing the dropdown.
- **Multi-Select**: Allows users to select multiple items from the dropdown.
- **Searchable Items**: Filter items based on search input.
- **Customizable Styles**: Full control over dropdown appearance, button, items, and more.
- **Loading State**: Show a loading spinner while fetching data.
- **Empty State**: Display a message when no items are available.
- **Clear Selections**: Clear selected items in multi-select mode.
- **Responsive**: Works well on all screen sizes.

## Installation

You can install `nim-react-dropdown` via npm:

```bash
npm install nim-react-dropdown
```

## Or with Yarn:

```
yarn add nim-react-dropdown
```

## Dependencies

- react-native-reanimated: For smooth animations when opening and closing the dropdown.

- react-native-gesture-handler: Required by react-native-reanimated.

- react-native-paper: Optional, for Material Design components (like buttons).

## Additional Setup for react-native-reanimated:

Follow the installation guide
to ensure react-native-reanimated is correctly configured.

### Usage

## Basic Example

Here’s a basic example of how to use the dropdown in your React Native app:

```
import React, { useState } from 'react';
import { View } from 'react-native';
import { Dropdown } from 'nim-react-dropdown';

const App = () => {
const [selectedItems, setSelectedItems] = useState([]);

const items = [
{ label: 'Apple', value: 'apple' },
{ label: 'Banana', value: 'banana' },
{ label: 'Orange', value: 'orange' },
];

const handleSelect = (item) => {
console.log(item);
};

const handleClearSelection = () => {
setSelectedItems([]);
};

return (
<View style={{ padding: 20 }}>
<Dropdown
        items={items}
        onSelect={handleSelect}
        multiSelect={true}
        selectedItems={selectedItems}
        onClearSelection={handleClearSelection}
        placeholder="Select fruits"
        loading={false}
      />
</View>
);
};
```

export default App;

## Props

items: Required — An array of objects representing the dropdown items, where each object should have a label and value.

## Example:

```const items = [
{ label: 'Apple', value: 'apple' },
{ label: 'Banana', value: 'banana' },
{ label: 'Orange', value: 'orange' },
];

```

onSelect: Required — A function to handle the selection of an item. The selected item’s value is passed as an argument.

multiSelect: Optional — A boolean to enable multiple selection. Default is false.

selectedItems: Optional — An array of selected items' values (used with multiSelect).

onClearSelection: Optional — A function to clear selected items when multi-select is enabled.

placeholder: Optional — A placeholder text for the dropdown button.

loading: Optional — A boolean to show a loading spinner while fetching items.

searchEnabled: Optional — A boolean to enable the search bar for filtering items. Default is true.

showEmptyState: Optional — A boolean to show a message when no items are available or when search results are empty. Default is false.

emptyStateText: Optional — Custom text to display when no items are available or when search results are empty. Default is "No items available".

disableDropdown: Optional — A boolean to disable the dropdown button. Default is false.

customStyles: Optional — An object to customize the dropdown, button, input, item, and other elements.

## Example:

```const customStyles = {
container: { borderColor: 'blue' },
button: { backgroundColor: 'lightblue' },
item: { borderBottomWidth: 1 },
input: { borderColor: 'gray' },
};
```

## Advanced Features

1. Smooth Animation

The dropdown smoothly opens and closes with a spring animation. This is achieved using react-native-reanimated.

2. Multi-Select

Enables users to select multiple items. The selectedItems prop tracks the selected values, and checkboxes appear next to each item.

3. Searchable Items

A search bar allows users to filter items in the dropdown. This can be enabled or disabled with the searchEnabled prop.

4. Custom Styles

You can easily customize the appearance of the dropdown with the customStyles prop. This allows you to style the dropdown button, items, input field, and more.

5. Loading and Empty State

The dropdown can show a loading spinner when fetching data. Additionally, it displays a message when no items are available or when search results are empty.

6. Clear Selections (Multi-Select Only)

In multi-select mode, users can clear their selections with the "Clear" button.

## Contributing

We welcome contributions to nim-react-dropdown! If you'd like to contribute, please follow these steps:

Fork the repository.

Clone your fork and create a new branch.

Make your changes and write tests (if applicable).

Open a pull request to the main branch.

## License

nim-react-dropdown is licensed under the MIT License. See the LICENSE
file for more details.