npm package: @ibrahimstudio/select
Description: @ibrahimstudio/select is a highly customizable and reusable dropdown menu for React applications.
Author: Ibrahim Space Studio
Latest version: 1.0.5

<div align="center">
  <img width="20%" src="https://raw.githubusercontent.com/space-ibrahimstudio/ibrahimstudio/master/public/image/iss-logo.png" alt="@ibrahimstudio/select" />
  <h1>@ibrahimstudio/select</h1>
</div>

[@ibrahimstudio/select](https://github.com/space-ibrahimstudio/ibrahimstudio/tree/main/packages/components/select) is a highly customizable and reusable dropdown menu for React applications. This component is designed for seamless integration, offering advanced features such as searchable options, dynamic customization, and an intuitive user interface.

Its flexibility and ease of use make it an excellent choice for developers looking to streamline their workflow while ensuring a consistent and polished user experience.

Code by [Ibrahim Space Studio](https://space.ibrahimstudio.co), Design by [Ibrahim Design Studio](https://design.ibrahimstudio.co).

## 1. Features

- **Fully Customizable Design**: Supports custom colors, border radius, and more to match your application’s theme.
- **Searchable Dropdown**: Built-in search functionality for better usability with large datasets.
- **Dynamic Option Handling**: Accepts dynamic data and provides callbacks for seamless integration with APIs.
- **Accessibility**: Designed with accessibility in mind, ensuring usability for all users.
- **Event Handling**: Provides hooks for actions like selection and search input changes.

## 2. Installation

You can install this package via npm:

```sh
npm i @ibrahimstudio/select
```

or via yarn:

```sh
yarn add @ibrahimstudio/select
```

## 3. Usage

Import the Select component in your React application:

```javascript
import { Select } from "@ibrahimstudio/select";
```

### Defining the `options` Prop

The `options` prop is an array of objects, where each object contains two required fields:

- `value` (`string` or `number`): The unique value of the option.
- `label` (`string`): The text displayed in the dropdown menu.

```js
const options = [
  { value: 1, label: "Option 1" },
  { value: 2, label: "Option 2" },
  { value: 3, label: "Option 3" },
];
```

### Handling the `onChange` Callback

The `onChange` prop is a function triggered whenever a user selects an option. The callback receives the `value` of the selected option.

```js
const handleSelect = (value) => {
  console.log("Selected value:", value);
};
```

If the user selects "Option 1", the console will log:

```yaml
Selected value: 1
```

### Adding Search Functionality with `searchable`

To enable the search functionality, set the `searchable` prop to `true`. By default, the search box will filter the options array based on the entered search term without requiring any additional setup.

If you want custom behavior, such as fetching options dynamically from an API or handling search input differently, you can define the `onSearch` prop.

**Default Search Behavior (Without `onSearch`)**

```jsx
<Select name="fruits" searchable options={options} onChange={handleSelect} />
```

- When `searchable` is set to `true` and no `onSearch` is defined, the component automatically filters the options based on the label field.
- When the user types "ap" in the search box, only the "Apple" option is displayed.
- No additional coding is required for this filtering.

**Custom Search Behavior with `onSearch`**

When you define an `onSearch` prop, you can customize how search input is handled. For example, you can fetch data from an API or apply additional filtering logic.

Setup the handler:

```javascript
const [options, setOptions] = useState([]);

const handleSearchChange = (searchTerm) => {
  console.log("Search term:", searchTerm);

  // Simulate API request
  fetch(`/api/fruits?query=${searchTerm}`)
    .then((res) => res.json())
    .then((data) => setOptions(data))
    .catch((error) => console.error("Error fetching fruits:", error));
};
```

Usage on JSX:

```jsx
<Select name="fruits" searchable onSearch={handleSearchChange} options={options} onChange={handleSelect} />
```

- When the user types into the search box, the `handleSearchChange` function is triggered with the current search term.
- The app fetches matching options from an API endpoint.
- The dropdown menu displays the dynamically fetched options.

## 4. API

### Select Props

| Attribute     | Type                                            | Required | Description                                                                  | Depend To        | Default                          |
| ------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------- | ---------------- | -------------------------------- |
| `id`          | `string`                                        | Yes      | Unique identifier for the component.                                         | -                | `'@ibrahimstudio/select'`        |
| `form`        | `string`                                        | -        | Form identifier to associate with the input.                                 | -                | -                                |
| `name`        | `string`                                        | Yes      | Name attribute for the input element.                                        | -                | `'select'`                       |
| `label`       | `string`                                        | Yes      | Text for the label above the dropdown.                                       | `labeled='true'` | `'ISS Select'`                   |
| `placeholder` | `string`                                        | -        | Placeholder text displayed when no value is selected.                        | -                | `'Select Item'`                  |
| `value`       | `string` `number`                               | Yes      | The selected value of the component.                                         | -                | -                                |
| `options`     | `array`                                         | -        | Array of options with `value` and `label`.                                   | -                | `[]`                             |
| `radius`      | `'none'` `'sm'` `'md'` `'lg'` `'full'` `string` | -        | Border radius options.                                                       | -                | `'md'`                           |
| `bcolor`      | `string`                                        | -        | The base color of the component, e.g., `#000` or a CSS variable.             | -                | `'var(--theme-color-base)'`      |
| `pcolor`      | `string`                                        | -        | The primary color for active or highlighted states.                          | -                | `'var(--theme-color-primary)'`   |
| `scolor`      | `string`                                        | -        | The secondary color for supporting elements like icons.                      | -                | `'var(--theme-color-secondary)'` |
| `labeled`     | `boolean`                                       | -        | Whether to display a label above the dropdown.                               | -                | `true`                           |
| `searchable`  | `boolean`                                       | -        | Enables a search input for filtering options.                                | -                | `false`                          |
| `noemptyval`  | `boolean`                                       | -        | Prevents empty values from being selected.                                   | -                | `false`                          |
| `optionwrap`  | `boolean`                                       | -        | Prevents option text overflow with ellipsis.                                 | -                | `false`                          |
| `required`    | `boolean`                                       | -        | Marks the input as required.                                                 | -                | `false`                          |
| `readonly`    | `boolean`                                       | -        | Makes the dropdown read-only.                                                | -                | `false`                          |
| `disabled`    | `boolean`                                       | -        | Disables the dropdown, preventing user interaction.                          | -                | `false`                          |
| `errormsg`    | `string`                                        | -        | Error message displayed below the dropdown.                                  | -                | -                                |
| `additmsg`    | `string`                                        | -        | Informational message displayed below the dropdown.                          | -                | -                                |
| `leadingicon` | `ReactNode`                                     | -        | Content displayed at the left of the input, e.g., an icon or custom element. | -                | -                                |

### Select Event(s)

| Attribute  | Type              | Required | Description                                       | Depend To           |
| ---------- | ----------------- | -------- | ------------------------------------------------- | ------------------- |
| `onChange` | `(value) => void` | Yes      | Callback triggered when an option is selected.    | -                   |
| `onSearch` | `(value) => void` | -        | Callback triggered when the search input changes. | `searchable='true'` |

## 5. Contributing

Contributions are welcome! If you have any improvements, bug fixes, or features, feel free to open an issue or create a pull request on GitHub.

## 6. License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/space-ibrahimstudio/ibrahimstudio/blob/master/LICENSE) file for details.