**Keyboard-friendly, accessible multi-select Svelte component.**
Docs
## Key features
- **Single / multiple select:** pass `maxSelect={1}` prop to only allow one selection
- **Dropdowns:** scrollable lists for large numbers of options
- **Searchable:** start typing to filter options
- **Tagging:** selected options are recorded as tags in the input
- **Server-side rendering:** no reliance on browser objects like `window` or `document`
- **Configurable:** see [props](#props)
- **No dependencies:** needs only Svelte as dev dependency
- **Keyboard friendly** for mouse-less form completion
## Recent breaking changes
- v3.0.0 changed the `event.detail` payload for `'add'`, `'remove'` and `'change'` events from `token` to `option`, e.g.
```js
on:add={(e) => console.log(e.detail.token.label)} // v2
on:add={(e) => console.log(e.detail.option.label)} // v3
```
It also added a separate event type `removeAll` for when the user removes all currently selected options at once which previously fired a normal `remove`. The props `ulTokensClass` and `liTokenClass` were renamed to `ulSelectedClass` and `liSelectedClass`. Similarly, the CSS variable `--sms-token-bg` changed to `--sms-selected-bg`.
- v4.0.0 renamed the slots for customizing how selected options and dropdown list items are rendered:
- old: ``, new: ``
- old: ``, new: ``
- v4.0.1 renamed the `readonly` prop to `disabled` which now prevents all form or user interaction with this component including opening the dropdown list which was still possible before. See [#45](https://github.com/janosh/svelte-multiselect/issues/45) for details. The associated CSS class applied to the outer `div` was likewise renamed to `div.multiselect.{readonly=>disabled}`.
- v4.0.3 CSS variables starting with `--sms-input-` were renamed to just `--sms-`. E.g. `--sms-input-min-height` is now `--sms-min-height`.
## Installation
```sh
yarn add -D svelte-multiselect
```
## Usage
```svelte
Favorite Frontend Frameworks?
selected = {JSON.stringify(selected)}
```
## Props
Full list of props/bindable variables for this component:
| name | default | description |
| :--------------------- | :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options` | required prop | Array of strings/numbers or `Option` objects that will be listed in the dropdown. See `src/lib/index.ts` for admissible fields. The `label` is the only mandatory one. It must also be unique. |
| `showOptions` | `false` | Bindable boolean that controls whether the options dropdown is visible. |
| `searchText` | `` | Text the user-entered to filter down on the list of options. Binds both ways, i.e. can also be used to set the input text. |
| `activeOption` | `null` | Currently active option, i.e. the one the user currently hovers or navigated to with arrow keys. |
| `maxSelect` | `null` | Positive integer to limit the number of options users can pick. `null` means no limit. |
| `selectedOptions` | `[]` | Array of currently/pre-selected options when binding/passing as props respectively. |
| `selectedLabels` | `[]` | Labels of currently selected options. |
| `selectedValues` | `[]` | Values of currently selected options. |
| `sourceOfTruth` | `'options'` | The selected array chosen to be the source for all the other selected arrays meaning changes to it will be reflected in the other arrays, of type `'options' \| 'labels' \| 'values'`. |
| `noOptionsMsg` | `'No matching options'` | What message to show if no options match the user-entered search string. |
| `disabled` | `false` | Disable the component. It will still be rendered but users won't be able to interact with it. |
| `disabledTitle` | `This field is disabled` | Tooltip text to display on hover when the component is in `disabled` state. |
| `placeholder` | `undefined` | String shown in the text input when no option is selected. |
| `input` | `null` | Handle to the `` DOM node. Only available after component mounts (`null` before then). |
| `outerDiv` | `null` | Handle to outer `
` that wraps the whole component. Only available after component mounts (`null` before then). |
| `id` | `undefined` | Applied to the `` element for associating HTML form `
## Exposed methods
1. `filterFunc = (op: Option, searchText: string) => boolean`: Determine what options are shown when user enters search string to filter dropdown list. Defaults to:
```ts
filterFunc = (op: Option, searchText: string) => {
if (!searchText) return true
return `${op.label}`.toLowerCase().includes(searchText.toLowerCase())
}
```
2. `maxSelectMsg = (current: number, max: number) => string`: Inform users how many of the maximum allowed options they have already selected. Set `maxSelectMsg={null}` to not show a message. Defaults to `null` when `maxSelect={1}` or `maxSelect={null}`. Else if `maxSelect > 1`, defaults to:
```ts
maxSelectMsg = (current: number, max: number) => `${current}/${max}`
```
## Slots
`MultiSelect.svelte` has 3 named slots:
- `slot="option"`: Customize rendering of dropdown options. Receives as props the `option` object and the zero-indexed position (`idx`) it has in the dropdown.
- `slot="selected"`: Customize rendering selected tags. Receives as props the `option` object and the zero-indexed position (`idx`) it has in the list of selected items.
- `slot="spinner"`: Custom spinner component to display when in `loading` state. Receives no props.
- `slot="disabled-icon"`: Custom icon to display inside the input when in `disabled` state. Receives no props. Use an empty `` or `div` to remove the default disabled icon.
Example:
```svelte
{idx + 1}
{option.label}
{idx + 1}
{option.label}
```
## Events
`MultiSelect.svelte` dispatches the following events:
| name | detail | description |
| ----------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `add` | `{ option: Option }` | Triggers when a new option is selected. |
| `remove` | `{ option: Option }` | Triggers when one selected option provided as `event.detail.option` is removed. |
| `removeAll` | `options: Option[]` | Triggers when all selected options are removed. The payload `event.detail.options` gives the options that were previously selected. |
| `change` | `type: 'add' \| 'remove' \| 'removeAll'` | Triggers when a option is either added or removed, or all options are removed at once. Payload will be a single or an aarray of `Option` objects, respectively. |
| `blur` | none | Triggers when the input field looses focus. |
### Examples
- `on:add={(event) => console.log(event.detail.option.label)}`
- `on:remove={(event) => console.log(event.detail.option.label)}`.
- ``on:change={(event) => console.log(`${event.detail.type}: '${event.detail.option.label}'`)}``
- `on:blur={yourFunctionHere}`
```svelte
alert(`You ${e.detail.type}ed '${e.detail.option.label}'`)}
/>
```
## TypeScript
TypeScript users can import the types used for internal type safety:
```svelte
```
## Styling
There are 3 ways to style this component. To understand which options do what, it helps to keep in mind this simplified DOM structure of the component:
```svelte
Svelte MultiSelect