Keyboard-friendly, accessible and highly customizable multi-select component.
View the docs
## ๐ก Features
- **Bindable:** `bind:selected` gives you an array of the currently selected options. Thanks to Svelte's 2-way binding, it can also control the component state externally through assignment `selected = ['foo', 42]`.
- **Keyboard friendly** for mouse-less form completion
- **No run-time deps:** needs only Svelte as dev dependency
- **Dropdowns:** scrollable lists for large numbers of options
- **Searchable:** start typing to filter options
- **Tagging:** selected options are listed as tags within the input
- **Single / multiple select:** pass `maxSelect={1, 2, 3, ...}` prop to restrict the number of selectable options
- **Configurable:** see props
## ๐งช Coverage
| Statements | Branches | Lines |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
|  |  |  |
## ๐จ Installation
```sh
npm install --dev svelte-multiselect
```
## ๐ Usage
```svelte
Favorite Frontend Tools?
selected = {JSON.stringify(selected)}
```
## ๐ง Mental Model
| Prop | Purpose | Value |
| --------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `options` | What users can choose from | Array of strings, numbers, or objects with `label` property |
| `bind:selected` | Which options users have chosen | Always an array: `[]`, `['Apple']` or `['Apple', 'Banana']` |
| `bind:value` | Single-select convenience for the user-selected option | Single item: `'Apple'` (or `null`) if `maxSelect={1}`, otherwise same as `selected` |
### Common Patterns
```svelte
```
### Troubleshooting
- **Object options not working?** โ Add `label` property
- **Dropdown not showing?** โ Check you have `options` and not `disabled={true}`
- **Want single item not array?** โ Use `bind:value` with `maxSelect={1}`
- **Types confusing?** โ Component auto-infers type of `selected` and `value` from your `options` array
## ๐ฃ Props
Complete reference of all props. Props are organized by importance - **Essential Props** are what you'll use most often.
> **๐ก Tip:** The `Option` type is automatically inferred from your `options` array, or you can import it: `import { type Option } from 'svelte-multiselect'`
### Essential Props
These are the core props you'll use in most cases:
1. ```ts
options?: Option[] // required unless loadOptions is provided
```
Array of strings, numbers, or objects that users can select from. Objects must have a `label` property that will be displayed in the dropdown. Omit this when using `loadOptions` as the source of dynamic options.
```svelte
```
1. ```ts
selected: Option[] = [] // bindable
```
**Your main state variable.** Array of currently selected options. Use `bind:selected` for two-way binding.
```svelte
```
1. ```ts
value: Option | Option[] | null = null // bindable
```
**Alternative to `selected`.** When `maxSelect={1}`, `value` is the single selected item (not an array). Otherwise, `value` equals `selected`.
```svelte
```
1. ```ts
maxSelect: number | null = null
```
**Controls selection behavior.** `null` = unlimited, `1` = single select, `2+` = limited multi-select.
```svelte
```
1. ```ts
placeholder: string | { text: string; persistent?: boolean } | null = null
```
Text shown when no options are selected. Can be a simple string or an object with extended options:
```svelte
```
1. ```ts
disabled: boolean = false
```
Disables the component. Users can't interact with it, but it's still rendered.
1. ```ts
required: boolean | number = false
```
For form validation. `true` means at least 1 option required, numbers specify exact minimum.
### Commonly Used Props
1. ```ts
searchText: string = `` // bindable
```
The text user entered to filter options. Bindable for external control.
1. ```ts
open: boolean = false // bindable
```
Whether the dropdown is visible. Bindable for external control.
1. ```ts
allowUserOptions: boolean | `append` = false
```
Whether users can create new options by typing. `true` = add to selected only, `'append'` = add to both options and selected.
1. ```ts
allowEmpty: boolean = false
```
Whether to allow the component to exist with no options. If `false`, shows console error when no options provided (unless `loading`, `disabled`, or `allowUserOptions` is `true`).
1. ```ts
loading: boolean = false
```
Shows a loading spinner. Useful when fetching options asynchronously.
1. ```ts
invalid: boolean = false // bindable
```
Marks the component as invalid (adds CSS class). Automatically set during form validation.
### Advanced Props
1. ```ts
loadOptions: LoadOptionsFn | LoadOptionsConfig = undefined
```
**Dynamic loading for large datasets.** Enables lazy loading / infinite scroll instead of passing static `options`. Pass either a function or an object with config:
```svelte
```
The function receives `{ search, offset, limit }` and must return `{ options, hasMore }`:
```ts
async function load_options({ search, offset, limit }) {
const response = await fetch(`/api/items?q=${search}&skip=${offset}&take=${limit}`)
const { items, total } = await response.json()
return { options: items, hasMore: offset + limit < total }
}
```
Config options (when passing an object):
| Key | Type | Default | Description |
| ------------ | --------- | ------- | ------------------------------------------- |
| `fetch` | `fn` | โ | Async function to load options (required) |
| `debounceMs` | `number` | `300` | Debounce delay for search queries |
| `batchSize` | `number` | `50` | Number of options to load per batch |
| `onOpen` | `boolean` | `true` | Whether to load options when dropdown opens |
Features automatic state management, debounced search, infinite scroll pagination, and loading indicators. See the [infinite-scroll demo](https://janosh.github.io/svelte-multiselect/infinite-scroll) for live examples.
1. ```ts
activeIndex: number | null = null // bindable
```
Zero-based index of currently active option in the filtered list.
1. ```ts
activeOption: Option | null = null // bindable
```
Currently active option (hovered or navigated to with arrow keys).
1. ```ts
createOptionMsg: string | ((state: { searchText: string; selected: Option[]; options: Option[]; matchingOptions: Option[] }) => string) | null = `Create this option...`
```
Message shown when `allowUserOptions` is enabled and user can create a new option. Can be a static string or a function that receives component state and returns a dynamic message.
1. ```ts
duplicates: boolean | 'case-insensitive' = false
```
Controls duplicate detection. `false` (default) blocks exact duplicates. `true` allows selecting the same option multiple times. `'case-insensitive'` blocks case variants (e.g. "Apple" blocks "apple").
1. ```ts
expandIconPosition: 'left' | 'right' | 'none' = 'left'
```
Which side of the input to render the expand icon on, or `'none'` to hide it entirely (applies to both the default chevron and a custom `expandIcon` snippet). Clicking the icon toggles the dropdown.
1. ```ts
filterFunc: (opt: Option, searchText: string) => boolean
```
Custom function to filter options based on search text. Default filters by label.
1. ```ts
key: (opt: Option) => unknown
```
Function to determine option equality. Default compares by lowercased label.
1. ```ts
closeDropdownOnSelect: boolean | 'if-mobile' | 'retain-focus' = false
```
Whether to close dropdown after selection. `false` (default) keeps dropdown open for rapid multi-selection. `true` closes after each selection. `'if-mobile'` closes on mobile devices only (screen width below `breakpoint`). `'retain-focus'` closes dropdown but keeps input focused for rapid typing to create custom options from text input (see `allowUserOptions`).
1. ```ts
resetFilterOnAdd: boolean = true
```
Whether to clear search text when an option is selected.
1. ```ts
sortSelected: boolean | ((a: Option, b: Option) => number) = false
```
Whether/how to sort selected options. `true` uses default sort, function enables custom sorting.
1. ```ts
portal: { target_node?: HTMLElement; active?: boolean } = {}
```
Configuration for portal rendering. When `active: true`, the dropdown is rendered at document.body level with fixed positioning. Useful for avoiding z-index and overflow issues.
### Grouping Props
Group related options together with visual headers. Add a `group` key to your option objects:
```svelte
```
See the [grouping demo](https://janosh.github.io/svelte-multiselect/grouping) for live examples.
1. ```ts
collapsibleGroups: boolean = false
```
Enable click-to-collapse groups. When `true`, users can click group headers to hide/show options in that group.
1. ```ts
collapsedGroups: Set = new Set()
```
Bindable set of collapsed group names. Use `bind:collapsedGroups` to control which groups are collapsed externally or to persist collapse state.
1. ```ts
groupSelectAll: boolean = false
```
Add a "Select all" button to each group header, allowing users to select all options in a specific group at once.
1. ```ts
ungroupedPosition: 'first' | 'last' = 'first'
```
Where to render options that don't have a `group` key. `'first'` places them at the top, `'last'` at the bottom.
1. ```ts
groupSortOrder: 'none' | 'asc' | 'desc' | ((a: string, b: string) => number) = 'none'
```
Sort groups alphabetically (`'asc'` or `'desc'`) or with a custom comparator function. Default `'none'` preserves order of first occurrence.
1. ```ts
searchExpandsCollapsedGroups: boolean = false
```
When `true`, collapsed groups automatically expand when the search query matches options within them.
1. ```ts
searchMatchesGroups: boolean = false
```
When `true`, the search query also matches against group names, not just option labels. If a group name matches, all options in that group are shown.
1. ```ts
keyboardExpandsCollapsedGroups: boolean = false
```
When `true`, collapsed groups automatically expand when the user navigates into them with arrow keys.
1. ```ts
stickyGroupHeaders: boolean = false
```
When `true`, group headers stick to the top of the dropdown while scrolling through their options.
1. ```ts
collapseAllGroups: () => void // bindable
```
Programmatically collapse all groups. Use with `bind:collapseAllGroups` to get a callable function.
1. ```ts
expandAllGroups: () => void // bindable
```
Programmatically expand all groups. Use with `bind:expandAllGroups` to get a callable function.
1. ```ts
liGroupHeaderClass: string = ''
```
CSS class applied to group header `
` elements.
1. ```ts
liGroupHeaderStyle: string | null = null
```
Inline style for group header elements.
1. ```ts
groupHeader: Snippet<[{ group: string; options: T[]; collapsed: boolean }]>
```
Custom snippet for rendering group headers. Receives the group name, array of options in that group, and whether the group is collapsed.
1. ```ts
ongroupToggle: (data: { group: string; collapsed: boolean }) => void
```
Callback fired when a group is collapsed or expanded. Receives the group name and its new collapsed state.
### Form & Accessibility Props
1. ```ts
id: string | null = null
```
Applied to the `` for associating with `
Svelte MultiSelect