94b32be5d3
We want to enable a mode that prevent the pills the wrap on multiple lines in order to control any height overflowing. In monoline mode the selected items are displayed as text to allow text ellipsis, and the menu renders the list items with checkboxes.
146 lines
5.0 KiB
Plaintext
146 lines
5.0 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>
|
|
<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>
|
|
|
|
## 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 sourceState="shown">
|
|
<Story id="components-forms-select-multi--monoline"/>
|
|
</Canvas>
|
|
|
|
## 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 sourceState="shown">
|
|
<Story id="components-forms-select-multi--searchable-custom-render"/>
|
|
</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 |
|