Svelte MultiSelect


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 |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| !Statements | !Branches | !Lines |

🔨   Installation

``sh
npm install --dev svelte-multiselect
pnpm add -D svelte-multiselect
yarn add --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 |

$3

`svelte




bind:selected
options={[
{ label: 'Red', value: '#ff0000' },
{ label: 'Blue', value: '#0000ff' },
]}
/>
`

$3

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

$3

These are the core props you'll use in most cases:

1. `ts
options: Option[] // REQUIRED
`

The only required prop. Array of strings, numbers, or objects that users can select from. Objects must have a label property that will be displayed in the dropdown.

`svelte




options={[
{ label: 'Red', value: '#ff0000', hex: true },
{ label: 'Green', value: '#00ff00', hex: true },
]}
/>
`

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.

$3

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.

$3

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 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 | null = Create this option...
`

Message shown when allowUserOptions is enabled and user can create a new option.

1. `ts
duplicates: boolean = false
`

Whether to allow selecting the same option multiple times.


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.

$3

Group related options together with visual headers. Add a group key to your option objects:

`svelte



`

See the grouping demo 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
liGroupHeaderClass: string = ''
`

CSS class applied to group header