cunningham/packages/react/src/components/Forms/Select/multi.mdx

import { Canvas, Meta, Story } from '@storybook/blocks';
import * as Stories from './multi.stories';

<Meta of={Stories} name="Docs"/>

# Multi-Select

Cunningham provides a versatile Multi-Select component that you can use in your forms. This component follows the [ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/)
using [Downshift](https://www.downshift-js.com/), so that mean there is no `select` wrapped inside it.

The Multi-Select leverages the regular [Select](?path=/docs/components-forms-select-mono--docs) component, you just have to add the `multi` props.

<Canvas of={Stories.FullWidth}/>

## Options

The `options` props works the same as the `options` props in the [Select](?path=/docs/components-forms-select-mono--docs#options) component.

## Searchable

You can enable the text live filtering simply by using the `searchable` props.

<Canvas of={Stories.SearchableUncontrolled}/>

> You can use `onSearchInputChange` to get the value of the input when the user is typing.

## States

You can use the following props to change the state of the Multi-Select component by using the `state` props.

<Canvas of={Stories.Success}/>
<Canvas of={Stories.Error}/>

## Disabled

As a regular select, you can disable it by using the `disabled` props. In this mode the user can't select nor unselect existing options.

<Canvas of={Stories.Disabled}/>

## Texts

As the component uses [Field](?path=/docs/components-forms-field--docs), you can use the `text` props to provide a description of the checkbox.

<Canvas of={Stories.WithText}/>

## Width

By default, the Multi-Select has a default width, like all inputs. But you can force it to take the full width of its container by using the `fullWidth` props.

<Canvas of={Stories.FullWidth}/>

## Clearable

By default, the Multi-Select is clearable ( the cross icon on the right is shown ). You can disable it by using the `clearable` props.

<Canvas of={Stories.NotClearable}/>

## Disabled options

You can disable some options by using the `disabled` props on the `Option` object.

<Canvas of={Stories.DisabledOptions}/>

## Hide label

For some reasons you might want to hide the label of the Multi-Select. You can do that by using the `hideLabel` props.

> It is important for accessibility to always have a label for your inputs. Keep in mind that setting `hideLabel` to `true`, will only hide the label visually, but it will still be available for screen readers in the DOM.

<Canvas of={Stories.HiddenLabel}/>

## Monoline

You can use `monoline` props in order to make sure the component will never wrap on multiple lines.
When using this mode the selected options will be kept in the menu with checkboxes in order to make sure the user can
always see the full list of selected options without having to scroll.

> At the moment this props cannot be used in conjunction with `searchable` props.

<Canvas of={Stories.Monoline}/>

## Custom render option

You can give customize the look of the options by providing `render` callback.

> When you provide `render` the fields `label` and `value` are mandatory.

Feel free to use the attribute `showLabelWhenSelected` to choose whether you want to display selected option with the custom
HTML or with its `label`. It is set to `true` by default.

<Canvas of={Stories.SearchableCustomRender}/>

## Controlled / Non Controlled

Like a native select, you can use the Select component in a controlled or non controlled way. You can see the example below
using the component in a controlled way.

<Canvas of={Stories.Controlled}/>

## Usage with react-hook-form

You can use this input with [react-hook-form](https://react-hook-form.com/docs)

<Canvas of={Stories.ReactHookForm}/>

## Props

They are the same as the [Select](?path=/docs/components-forms-select-mono--docs#props) component.

## Design tokens

They are the same as the [Select](?path=/docs/components-forms-select-mono--docs#design-tokens) component plus the following:

| Token        	| Description                 	|
|---------------	|-----------------------------	|
| multi-pill-background-color	| Background color of the pills of the multi select    	|
| multi-pill-border-radius	| Border radius of the pills of the multi select    	|
| multi-pill-max-width	| Max width of pills	|