c63aff4861
The old way of using Canvas is deprecated, we need to migrate all the stories to the new standard.
119 lines
4.2 KiB
Plaintext
119 lines
4.2 KiB
Plaintext
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 |
|