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>
  <Story id="components-forms-select-multi--full-width"/>
</Canvas>

## 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 sourceState="shown">
  <Story id="components-forms-select-multi--searchable-uncontrolled"/>
</Canvas>

## States

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

<Canvas sourceState="shown">
  <Story id="components-forms-select-multi--success"/>
</Canvas>

<Canvas sourceState="shown">
  <Story id="components-forms-select-multi--error"/>
</Canvas>

## 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 sourceState="shown">
  <Story id="components-forms-select-multi--disabled"/>
</Canvas>

## 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 sourceState="shown">
  <Story id="components-forms-select-multi--with-text"/>
</Canvas>

## 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 sourceState="shown">
  <Story id="components-forms-select-multi--full-width"/>
</Canvas>

## 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 sourceState="shown">
  <Story id="components-forms-select-multi--not-clearable"/>
</Canvas>

## Disabled options

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

<Canvas sourceState="shown">
  <Story id="components-forms-select-multi--disabled-options"/>
</Canvas>

## 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 sourceState="shown">
  <Story id="components-forms-select-multi--hidden-label"/>
</Canvas>

## 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 sourceState="shown">
  <Story id="components-forms-select-multi--controlled"/>
</Canvas>

## Usage with react-hook-form

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

<Canvas sourceState="shown">
  <Story id="components-forms-select-multi--react-hook-form"/>
</Canvas>

## 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	|