npm package: @lockmondan/select-custom
Description: A select custom for react and next
Author: lockmondan
Latest version: 0.6.0

# select-custom

Customizable select component for React and Next.js.

# Understanding the Elements

In this package, you will find 2 elements, `Select` and `Option`, which allow you to customize them as you wish.

These elements use classes generated by Tailwind CSS for their default styling. To replace these generated classes with your own Tailwind classes, you can use the `tailwind-merge` package, enabling you to style them however you like.

# How to Style Them?

To style these elements, both have a `className` property. However, there is a difference: the `Select` component works a bit differently from the `Option` component.

## `Select`

The `className` property uses an interface named `ClassNameSelect`, which consists of three attributes: `classNameRoot`, `classNameView`, and `classNameOptions`. Each of these attributes is responsible for a specific part of styling the `Select` component.

1. `classNameRoot`: It takes a `string` type and is responsible for wrapping the entire `Select` element.

2. `classNameView`: It can receive either the `ClassNameSelectView` interface or a `string`, and it is responsible for the display of the selected value. The `ClassNameSelectView` interface has four attributes:

    - `style`: Styles the entire view area of the `Select`.
    
    - `whenShowOptions`: Modifies styling when the options list is shown.
    
    - `whenHiddenOptions`: Modifies styling when the options list is hidden.
    
    - `input`: Styles the input component.

3. `classNameOptions`: It can receive the `ClassNameSelectComponent` type or a `string`, and it is responsible for styling the options list. The `ClassNameSelectComponent` interface has three attributes:

    - `style`: Styles the entire options list.
    
    - `whenShowOptions`: Modifies styling when the options list is shown.
    
    - `whenHiddenOptions`: Modifies styling when the options list is hidden.

## `Option`

The `className` property accepts only the `string` type, allowing you to style the entire component as you prefer.

# How to Use Them?

To use these components, the process is similar to using traditional `select` and `option` elements. The `Select` component should be the parent element that wraps all `Option` elements. See the example below:

```jsx
<Select name="car" value="0">
  <Option value="0" text="Ferrari" />
  <Option value="1" text="Porsche" />
</Select>
```

In this example, `Select` is the main container, and each `Option` represents a choice available within the `Select`.

## `Select`

The `Select` component has some required attributes: `name`, `value`, and `children`.

- `name`: Type `string`, is required as it is the key to capture the selected value, especially useful in a `form` with **server actions**.

- `value`: Type `string`, sets the initially selected value from one of the options. If the value is not found, it will default to an empty string and display a default placeholder "Select an Option".

- `children`: The `Select` element must contain at least one `Option` element.

### Optional Attributes

- `showOptionsIcon` and `hiddenOptionsIcon`: Type `React.ElementType`, responsible for changing the icon that appears in the component's view. It is recommended to use the `react-icons` package for swapping icons.

- `sizeIcons`: Type `number`, changes the size of the icons in the view.

- `hiddenIcons`: Type `boolean`, hides the icons in the view.

## `Option`

The `Option` component has 2 required attributes: `value` and `text`.

- `value`: Type `string`. This property is directly tied to the `value` attribute of the `Select` element. When the page renders, the `Option` with the same `value` will be pre-selected by the `Select`.

  #### Example:
  ```jsx
  <Select name="car" value="0">
    <Option value="0" text="Ferrari" /> {/* Option pre-selected by Select */}
    <Option value="1" text="Porsche" />
  </Select>
  ```

- `text`: Type `string`. This property defines the text that will be displayed by the `Select` element when one of the options is selected.

### Optional Attributes:

- `placeholder`: Type `boolean`. When `true`, this property specifies that the text of the `Option` will be used as a placeholder in the `Select` element. Whenever this `Option` is selected, the `Select` value will be an empty string.

  #### Example:
  ```jsx
  <Select name="car" value="placeholder">
    <Option value="placeholder" text="Choose your car" placeholder />
    <Option value="0" text="Ferrari" />
    <Option value="1" text="Porsche" />
  </Select>
  ```

- `icon`: Type `React.ElementType`. This attribute adds an icon to the `Option` element. It is recommended to use the `react-icons` package to add the icon.


Well, that's all and feel free to use it.