Package detail

svelte-multiselect

janosh70.2kMIT11.0.0-rc.1

Svelte multi-select component

svelte, multi-select, single-select, form, input

readme

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

📜 Breaking changes

8.0.0 (2022-10-22)
- Props selectedLabels and selectedValues were removed. If you were using them, they were equivalent to assigning bind:selected to a local variable and then running selectedLabels = selected.map(option => option.label) and selectedValues = selected.map(option => option.value) if your options were objects with label and value keys. If they were simple strings/numbers, there was no point in using selected{Labels,Values} anyway. PR 138
- Prop noOptionsMsg was renamed to noMatchingOptionsMsg. PR 133.
v8.3.0 (2023-01-25) addOptionMsg was renamed to createOptionMsg (no major since version since it's rarely used) sha.
v9.0.0 (2023-06-01) Svelte bumped from v3 to v4. Also, not breaking but noteworthy: MultiSelect received a default slot that functions as both "option" and "selected". If you previously had two identical slots for "option" and "selected", you can now remove the name from one of them and drop the other:
```
<MultiSelect
  {options}
+ let:option
>
- <SlotComponent let:option {option} slot="selected" />
- <SlotComponent let:option {option} slot="option" />
+ <SlotComponent {option} />
</MultiSelect>
```
v10.0.0 (2023-06-23) duplicateFunc() renamed to key in #238. Signature changed:
```
- duplicateFunc: (op1: T, op2: T) => boolean = (op1, op2) => `${get_label(op1)}`.toLowerCase() === `${get_label(op2)}`.toLowerCase()
+ key: (opt: T) => unknown = (opt) => `${get_label(opt)}`.toLowerCase()
```
Rather than implementing custom equality in duplicateFunc, the key function is now expected to map options to a unique identifier. key(op1) === key(op2) should mean op1 and op2 are the same option. key can return any type but usually best to return primitives (string, number, ...) for Svelte keyed each blocks (see #217).

🔨 Installation

npm install --dev svelte-multiselect
pnpm add -D svelte-multiselect
yarn add --dev svelte-multiselect

📙 Usage

<script>
  import MultiSelect from 'svelte-multiselect'

  const ui_libs = [`Svelte`, `React`, `Vue`, `Angular`, `...`]

  let selected = []
</script>

Favorite Frontend Tools?

<code>selected = {JSON.stringify(selected)}</code>

<MultiSelect bind:selected options={ui_libs} />

🔣 Props

Full list of props/bindable variables for this component. The Option type you see below is defined in src/lib/index.ts and can be imported as import { type Option } from 'svelte-multiselect'.

```
activeIndex: number | null = null
```
Zero-based index of currently active option in the array of currently matching options, i.e. if the user typed a search string into the input and only a subset of options match, this index refers to the array position of the matching subset of options
```
activeOption: Option | null = null
```
Currently active option, i.e. the one the user currently hovers or navigated to with arrow keys.
```
createOptionMsg: string | null = `Create this option...`
```
The message shown to users when allowUserOptions is truthy and they entered text that doesn't match any existing options to suggest creating a new option from the entered text. Emits console.error if allowUserOptions is true or 'append' and createOptionMsg='' to since users might be unaware they can create new option. The error can be silenced by setting createOptionMsg=null indicating developer intent is to e.g. use MultiSelect as a tagging component where a user message might be unwanted.
```
allowEmpty: boolean = false
```
Whether to console.error if dropdown list of options is empty. allowEmpty={false} will suppress errors. allowEmpty={true} will report a console error if component is not disabled, not in loading state and doesn't allowUserOptions.
```
allowUserOptions: boolean | 'append' = false
```
Whether users can enter values that are not in the dropdown list. true means add user-defined options to the selected list only, 'append' means add to both options and selected. If allowUserOptions is true or 'append' then the type object | number | string of entered value is determined by typeof options[0] (i.e. the first option in the dropdown list) to keep type homogeneity.
```
autocomplete: string = `off`
```
Applied to the <input>. Specifies if browser is permitted to auto-fill this form field. Should usually be one of 'on' or 'off' but see MDN docs for other admissible values.
```
autoScroll: boolean = true
```
false disables keeping the active dropdown items in view when going up/down the list of options with arrow keys.
```
breakpoint: number = 800
```
Screens wider than breakpoint in pixels will be considered 'desktop', everything narrower as 'mobile'.
```
defaultDisabledTitle: string = `This option is disabled`
```
Title text to display when user hovers over a disabled option. Each option can override this through its disabledTitle attribute.
```
disabled: boolean = false
```
Disable the component. It will still be rendered but users won't be able to interact with it.
```
disabledInputTitle: string = `This input is disabled`
```
Tooltip text to display on hover when the component is in disabled state.
```
duplicates: boolean = false
```
Whether to allow users to select duplicate options. Applies only to the selected item list, not the options dropdown. Keeping that free of duplicates is left to developer. The selected item list can have duplicates if allowUserOptions is truthy, duplicates is true and users create the same option multiple times. Use duplicateOptionMsg to customize the message shown to user if duplicates is false and users attempt this and key to customize when a pair of options is considered equal.
```
duplicateOptionMsg: string = `This option is already selected`
```
Text to display to users when allowUserOptions is truthy and they try to create a new option that's already selected.

```
key: (opt: T) => unknown = (opt) => `${get_label(opt)}`.toLowerCase()
```
A function that maps options to a value by which equality of options is determined. Defaults to mapping options to their lower-cased label. E.g. by default const opt1 = { label: `foo`, id: 1 } and const opt2 = { label: `foo`, id: 2 } are considered equal. If you want to consider them different, you can set key to e.g. key={(opt) => opt.id} or key={(opt) => `${opt.label}-${opt.id}} or even key={JSON.stringify}.

filterFunc = (opt: Option, searchText: string): boolean => {
  if (!searchText) return true
  return `${get_label(opt)}`.toLowerCase().includes(searchText.toLowerCase())
}

Customize how dropdown options are filtered when user enters search string into <MultiSelect />. Defaults to:

```
closeDropdownOnSelect: boolean | 'desktop' = `desktop`
```
One of true, false or 'desktop'. Whether to close the dropdown list after selecting a dropdown item. If true, component will loose focus and dropdown is closed. 'desktop' means false if current window width is larger than the current value of breakpoint prop (default is 800, meaning screen width in pixels). This is to align with the default behavior of many mobile browsers like Safari which close dropdowns after selecting an option while desktop browsers facilitate multi-selection by leaving dropdowns open.
```
form_input: HTMLInputElement | null = null
```
Handle to the <input> DOM node that's responsible for form validity checks and passing selected options to form submission handlers. Only available after component mounts (null before then).
```
highlightMatches: boolean = true
```
Whether to highlight text in the dropdown options that matches the current user-entered search query. Uses the CSS Custom Highlight API with limited browser support (70% as of May 2023) and styling options. See ::highlight(sms-search-matches) below for available CSS variables.
```
id: string | null = null
```
Applied to the <input> element for associating HTML form <label>s with this component for accessibility. Also, clicking a <label> with same for attribute as id will focus this component.
```
input: HTMLInputElement | null = null
```
Handle to the <input> DOM node. Only available after component mounts (null before then).
```
inputmode: string | null = null
```
The inputmode attribute hints at the type of data the user may enter. Values like 'numeric' | 'tel' | 'email' allow mobile browsers to display an appropriate virtual on-screen keyboard. See MDN for details. If you want to suppress the on-screen keyboard to leave full-screen real estate for the dropdown list of options, set inputmode="none".
```
inputStyle: string | null = null
```
One-off CSS rules applied to the <input> element.
```
invalid: boolean = false
```
If required = true, 1, 2, ... and user tries to submit form but selected = [] is empty/selected.length < required, invalid is automatically set to true and CSS class invalid applied to the top-level div.multiselect. invalid class is removed as soon as any change to selected is registered. invalid can also be controlled externally by binding to it <MultiSelect bind:invalid /> and setting it to true based on outside events or custom validation.
```
liOptionStyle: string | null = null
```
One-off CSS rules applied to the <li> elements that wrap the dropdown options.
```
liSelectedStyle: string | null = null
```
One-off CSS rules applied to the <li> elements that wrap the selected options.
```
loading: boolean = false
```
Whether the component should display a spinner to indicate it's in loading state. Use <slot name='spinner'> to specify a custom spinner.
```
matchingOptions: Option[] = []
```
List of options currently displayed to the user. Same as options unless the user entered searchText in which case this array contains only those options for which filterFunc = (op: Option, searchText: string) => boolean returned true.
```
maxOptions: number | undefined = undefined
```
Positive integer to limit the number of options displayed in the dropdown. undefined and 0 mean no limit.
```
maxSelect: number | null = null
```
Positive integer to limit the number of options users can pick. null means no limit. maxSelect={1} will change the type of selected to be a single Option (or null) (not a length-1 array). Likewise, the type of selectedLabels changes from (string | number)[] to string | number | null and selectedValues from unknown[] to unknown | null. maxSelect={1} will also give div.multiselect a class of single. I.e. you can target the selector div.multiselect.single to give single selects a different appearance from multi selects.
```
maxSelectMsg: ((current: number, max: number) => string) | null = (
  current: number,
  max: number
) => (max > 1 ? `${current}/${max}` : ``)
```
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:
```
maxSelectMsg = (current: number, max: number) => `${current}/${max}`
```
Use CSS selector span.max-select-msg (or prop maxSelectMsgClass if you're using a CSS framework like Tailwind) to customize appearance of the message container.
```
minSelect: number | null = null
```
Conditionally render the x button which removes a selected option depending on the number of selected options. Meaning all remove buttons disappear if selected.length <= minSelect. E.g. if 2 options are selected and minSelect={3}, users will not be able to remove any selections until they selected more than 3 options.

Note: Prop required={3} should be used instead if you only care about the component state at form submission time. minSelect={3} should be used if you want to place constraints on component state at all times.
```
name: string | null = null
```
Applied to the <input> element. Sets the key of this field in a submitted form data object. See form example.
```
noMatchingOptionsMsg: string = `No matching options`
```
What message to show if no options match the user-entered search string.
```
open: boolean = false
```
Whether the dropdown list is currently visible. Is two-way bindable, i.e. can be used for external control of when the options are visible.
```
options: Option[]
```
The only required prop (no default). Array of strings/numbers or Option objects to be listed in the dropdown. The only required key on objects is label which must also be unique. An object's value defaults to label if undefined. You can add arbitrary additional keys to your option objects. A few keys like preselected and title have special meaning though. See type ObjectOption in /src/lib/types.ts for all special keys and their purpose.
```
outerDiv: HTMLDivElement | null = null
```
Handle to outer <div class="multiselect"> that wraps the whole component. Only available after component mounts (null before then).
```
parseLabelsAsHtml: boolean = false
```
Whether option labels should be passed to Svelte's @html directive or inserted into the DOM as plain text. true will raise an error if allowUserOptions is also truthy as it makes your site susceptible to cross-site scripting (XSS) attacks.
```
pattern: string | null = null
```
The pattern attribute specifies a regular expression which the input's value must match. If a non-null value doesn't match the pattern regex, the read-only patternMismatch property will be true. See MDN for details.
```
placeholder: string | null = null
```
String shown in the text input when no option is selected.
```
removeAllTitle: string = `Remove all`
```
Title text to display when user hovers over remove-all button.
```
removeBtnTitle: string = `Remove`
```
Title text to display when user hovers over button to remove selected option (which defaults to a cross icon).
```
required: boolean | number = false
```
If required = true, 1, 2, ... forms can't be submitted without selecting given number of options. true means 1. false means even empty MultiSelect will pass form validity check. If user tries to submit a form containing MultiSelect with less than the required number of options, submission is aborted, MultiSelect scrolls into view and shows message "Please select at least required options".
```
resetFilterOnAdd: boolean = true
```
Whether text entered into the input to filter options in the dropdown list is reset to empty string when user selects an option.
```
searchText: string = ``
```
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.
```
selected: Option[] =
 options
   ?.filter((op) => (op as ObjectOption)?.preselected)
   .slice(0, maxSelect ?? undefined) ?? []
```
Array of currently selected options. Supports 2-way binding bind:selected={[1, 2, 3]} to control component state externally. Can be passed as prop to set pre-selected options that will already be populated when component mounts before any user interaction.
```
sortSelected: boolean | ((op1: Option, op2: Option) => number) = false
```
Default behavior is to render selected items in the order they were chosen. sortSelected={true} uses default JS array sorting. A compare function enables custom logic for sorting selected options. See the /sort-selected example.
```
selectedOptionsDraggable: boolean = !sortSelected
```
Whether selected options are draggable so users can change their order.
```
style: string | null = null
```
One-off CSS rules applied to the outer <div class="multiselect"> that wraps the whole component for passing one-off CSS.
```
ulSelectedStyle: string | null = null
```
One-off CSS rules applied to the <ul class="selected"> that wraps the list of selected options.
```
ulOptionsStyle: string | null = null
```
One-off CSS rules applied to the <ul class="options"> that wraps the list of selected options.
```
value: Option | Option[] | null = null
```
If maxSelect={1}, value will be the single item in selected (or null if selected is empty). If maxSelect != 1, maxSelect and selected are equal. Warning: Setting value does not rendered state on initial mount, meaning bind:value will update local variable value whenever internal component state changes but passing a value when component first mounts won't be reflected in UI. This is because the source of truth for rendering is bind:selected. selected is reactive to value internally but only on reassignment from initial value. Suggestions for better solutions than #249 welcome!

🎰 Slots

MultiSelect.svelte accepts the following named slots:

slot="option": Customize rendering of dropdown options. Receives as props an option and the zero-indexed position (idx) it has in the dropdown.
slot="selected": Customize rendering of selected items. Receives as props an option 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 <span slot="disabled-icon" /> or div to remove the default disabled icon.
slot="expand-icon": Allows setting a custom icon to indicate to users that the Multiselect text input field is expandable into a dropdown list. Receives prop open: boolean which is true if the Multiselect dropdown is visible and false if it's hidden.
slot="remove-icon": Custom icon to display as remove button. Will be used both by buttons to remove individual selected options and the 'remove all' button that clears all options at once. Receives no props.
slot="user-msg": Displayed like a dropdown item when the list is empty and user is allowed to create custom options based on text input (or if the user's text input clashes with an existing option). Receives props:
- searchText: The text user typed into search input.
- msgType: false | 'create' | 'dupe' | 'no-match': 'dupe' means user input is a duplicate of an existing option. 'create' means user is allowed to convert their input into a new option not previously in the dropdown. 'no-match' means user input doesn't match any dropdown items and users are not allowed to create new options. false means none of the above.
- msg: Will be duplicateOptionMsg or createOptionMsg (see props) based on whether user input is a duplicate or can be created as new option. Note this slot replaces the default UI for displaying these messages so the slot needs to render them instead (unless purposely not showing a message).
slot='after-input': Placed after the search input. For arbitrary content like icons or temporary messages. Receives props selected: Option[], disabled: boolean, invalid: boolean, id: string | null, placeholder: string, open: boolean, required: boolean. Can serve as a more dynamic, more customizable alternative to the placeholder prop.

Example using several slots:

<MultiSelect options={[`Red`, `Green`, `Blue`, `Yellow`, `Purple`]} let:idx let:option>
   <!-- default slot overrides rendering of both dropdown-listed and selected options -->
  <span>
    {idx + 1}
    {option.label}
    <span style:background={option.label} style=" width: 1em; height: 1em;" />
  </span>

  <CustomSpinner slot="spinner">
  <strong slot="remove-icon">X</strong>
</MultiSelect>

🎬 Events

MultiSelect.svelte dispatches the following events:

```
on:add={(event) => console.log(event.detail.option)}
```
Triggers when a new option is selected. The newly selected option is provided as event.detail.option.
```
on:remove={(event) => console.log(event.detail.option)}`
```
Triggers when a single selected option is removed. The removed option is provided as event.detail.option.
```
on:removeAll={(event) => console.log(event.detail.options)}`
```
Triggers when all selected options are removed. The payload event.detail.options gives the options that were previously selected.
```
on:change={(event) => console.log(`${event.detail.type}: '${event.detail.option}'`)}
```
Triggers when an option is either added (selected) or removed from selected, or all selected options are removed at once. type is one of 'add' | 'remove' | 'removeAll' and payload will be option: Option or options: Option[], respectively.
```
on:open={(event) => console.log(`Multiselect dropdown was opened by ${event}`)}
```
Triggers when the dropdown list of options appears. Event is the DOM's FocusEvent,KeyboardEvent or ClickEvent that initiated this Svelte dispatch event.
```
on:close={(event) => console.log(`Multiselect dropdown was closed by ${event}`)}
```
Triggers when the dropdown list of options disappears. Event is the DOM's FocusEvent, KeyboardEvent or ClickEvent that initiated this Svelte dispatch event.

For example, here's how you might annoy your users with an alert every time one or more options are added or removed:

<MultiSelect
  on:change={(e) => {
    if (e.detail.type === 'add') alert(`You added ${e.detail.option}`)
    if (e.detail.type === 'remove') alert(`You removed ${e.detail.option}`)
    if (e.detail.type === 'removeAll') alert(`You removed ${e.detail.options}`)
  }}
/>

Note: Depending on the data passed to the component the options(s) payload will either be objects or simple strings/numbers.

The above list of events are Svelte dispatch events. This component also forwards many DOM events from the <input> node: blur, change, click, keydown, keyup, mousedown, mouseenter, mouseleave, touchcancel, touchend, touchmove, touchstart. Registering listeners for these events works the same:

<MultiSelect
  options={[1, 2, 3]}
  on:keyup={(event) => console.log('key', event.target.value)}
/>

🦺 TypeScript

The type of options is inferred automatically from the data you pass. E.g.

const options = [
   { label: `foo`, value: 42 }
   { label: `bar`, value: 69 }
]
// type Option = { label: string, value: number }
const options = [`foo`, `bar`]
// type Option = string
const options = [42, 69]
// type Option = number

The inferred type of Option is used to enforce type-safety on derived props like selected as well as slot components. E.g. you'll get an error when trying to use a slot component that expects a string if your options are objects (see this comment for example screenshots).

You can also import the types this component uses for downstream applications:

import {
  Option,
  ObjectOption,
  DispatchEvents,
  MultiSelectEvents,
} from 'svelte-multiselect'

✨ 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:

<div class="multiselect">
  <ul class="selected">
    <li>Selected 1</li>
    <li>Selected 2</li>
  </ul>
  <ul class="options">
    <li>Option 1</li>
    <li>Option 2</li>
  </ul>
</div>

With CSS variables

If you only want to make small adjustments, you can pass the following CSS variables directly to the component as props or define them in a :global() CSS context. See app.css for how these variables are set on the demo site of this component.

Minimal example that changes the background color of the options dropdown:

<MultiSelect --sms-options-bg="white" />

div.multiselect
- border: var(--sms-border, 1pt solid lightgray): Change this to e.g. to 1px solid red to indicate this form field is in an invalid state.
- border-radius: var(--sms-border-radius, 3pt)
- padding: var(--sms-padding, 0 3pt)
- background: var(--sms-bg)
- color: var(--sms-text-color)
- min-height: var(--sms-min-height, 22pt)
- width: var(--sms-width)
- max-width: var(--sms-max-width)
- margin: var(--sms-margin)
- font-size: var(--sms-font-size, inherit)
div.multiselect.open
- z-index: var(--sms-open-z-index, 4): Increase this if needed to ensure the dropdown list is displayed atop all other page elements.
div.multiselect:focus-within
- border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue)): Border when component has focus. Defaults to --sms-active-color which in turn defaults to cornflowerblue.
div.multiselect.disabled
- background: var(--sms-disabled-bg, lightgray): Background when in disabled state.
div.multiselect input::placeholder
- color: var(--sms-placeholder-color)
- opacity: var(--sms-placeholder-opacity)
div.multiselect > ul.selected > li
- background: var(--sms-selected-bg, rgba(0, 0, 0, 0.15)): Background of selected options.
- padding: var(--sms-selected-li-padding, 1pt 5pt): Height of selected options.
- color: var(--sms-selected-text-color, var(--sms-text-color)): Text color for selected options.
ul.selected > li button:hover, button.remove-all:hover, button:focus
- color: var(--sms-remove-btn-hover-color, lightskyblue): Color of the remove-icon buttons for removing all or individual selected options when in :focus or :hover state.
- background: var(--sms-remove-btn-hover-bg, rgba(0, 0, 0, 0.2)): Background for hovered remove buttons.
div.multiselect > ul.options
- background: var(--sms-options-bg, white): Background of dropdown list.
- max-height: var(--sms-options-max-height, 50vh): Maximum height of options dropdown.
- overscroll-behavior: var(--sms-options-overscroll, none): Whether scroll events bubble to parent elements when reaching the top/bottom of the options dropdown. See MDN.
- box-shadow: var(--sms-options-shadow, 0 0 14pt -8pt black): Box shadow of dropdown list.
- border: var(--sms-options-border)
- border-width: var(--sms-options-border-width)
- border-radius: var(--sms-options-border-radius, 1ex)
- padding: var(--sms-options-padding)
- margin: var(--sms-options-margin, inherit)
div.multiselect > ul.options > li
- scroll-margin: var(--sms-options-scroll-margin, 100px): Top/bottom margin to keep between dropdown list items and top/bottom screen edge when auto-scrolling list to keep items in view.
div.multiselect > ul.options > li.selected
- background: var(--sms-li-selected-bg): Background of selected list items in options pane.
- color: var(--sms-li-selected-color): Text color of selected list items in options pane.
div.multiselect > ul.options > li.active
- background: var(--sms-li-active-bg, var(--sms-active-color, rgba(0, 0, 0, 0.15))): Background of active options. Options in the dropdown list become active either by mouseover or by navigating to them with arrow keys. Selected options become active when selectedOptionsDraggable=true and an option is being dragged to a new position. Note the active option in that case is not the dragged option but the option under it whose place it will take on drag end.
div.multiselect > ul.options > li.disabled
- background: var(--sms-li-disabled-bg, #f5f5f6): Background of disabled options in the dropdown list.
- color: var(--sms-li-disabled-text, #b8b8b8): Text color of disabled option in the dropdown list.
::highlight(sms-search-matches): applies to search results in dropdown list that match the current search query if highlightMatches=true. These styles cannot be set via CSS variables. Instead, use a new rule set. For example:
```
::highlight(sms-search-matches) {
  color: orange;
  background: rgba(0, 0, 0, 0.15);
  text-decoration: underline;
}
```

With CSS frameworks

The second method allows you to pass in custom classes to the important DOM elements of this component to target them with frameworks like Tailwind CSS.

outerDivClass: wrapper div enclosing the whole component
ulSelectedClass: list of selected options
liSelectedClass: selected list items
ulOptionsClass: available options listed in the dropdown when component is in open state
liOptionClass: list items selectable from dropdown list
liActiveOptionClass: the currently active dropdown list item (i.e. hovered or navigated to with arrow keys)
liUserMsgClass: user message (last child of dropdown list when no options match user input)
liActiveUserMsgClass: user message when active (i.e. hovered or navigated to with arrow keys)
maxSelectMsgClass: small span towards the right end of the input field displaying to the user how many of the allowed number of options they've already selected

This simplified version of the DOM structure of the component shows where these classes are inserted:

<div class="multiselect {outerDivClass}">
  <input class={inputClass} />
  <ul class="selected {ulSelectedClass}">
    <li class={liSelectedClass}>Selected 1</li>
    <li class={liSelectedClass}>Selected 2</li>
  </ul>
  <span class="maxSelectMsgClass">2/5 selected</span>
  <ul class="options {ulOptionsClass}">
    <li class={liOptionClass}>Option 1</li>
    <li class="{liOptionClass} {liActiveOptionClass}">
      Option 2 (currently active)
    </li>
    ...
    <li class="{liUserMsgClass} {liActiveUserMsgClass}">
      Create this option...
    </li>
  </ul>
</div>

With global CSS

Odd as it may seem, you get the most fine-grained control over the styling of every part of this component by using the following :global() CSS selectors. ul.selected is the list of currently selected options rendered inside the component's input whereas ul.options is the list of available options that slides out when the component is in its open state. See also simplified DOM structure.

:global(div.multiselect) {
  /* top-level wrapper div */
}
:global(div.multiselect.open) {
  /* top-level wrapper div when dropdown open */
}
:global(div.multiselect.disabled) {
  /* top-level wrapper div when in disabled state */
}
:global(div.multiselect > ul.selected) {
  /* selected list */
}
:global(div.multiselect > ul.selected > li) {
  /* selected list items */
}
:global(div.multiselect button) {
  /* target all buttons in this component */
}
:global(div.multiselect > ul.selected > li button, button.remove-all) {
  /* buttons to remove a single or all selected options at once */
}
:global(div.multiselect > input[autocomplete]) {
  /* input inside the top-level wrapper div */
}
:global(div.multiselect > ul.options) {
  /* dropdown options */
}
:global(div.multiselect > ul.options > li) {
  /* dropdown list items */
}
:global(div.multiselect > ul.options > li.selected) {
  /* selected options in the dropdown list */
}
:global(div.multiselect > ul.options > li:not(.selected):hover) {
  /* unselected but hovered options in the dropdown list */
}
:global(div.multiselect > ul.options > li.active) {
  /* active means item was navigated to with up/down arrow keys */
  /* ready to be selected by pressing enter */
}
:global(div.multiselect > ul.options > li.disabled) {
  /* options with disabled key set to true (see props above) */
}

🆕 Changelog

View the changelog.

🙏 Contributing

Here are some steps to get you started if you'd like to contribute to this project!

changelog

Changelog

All notable changes to this project will be documented in this file. Dates are displayed in UTC.

v11.0.0-rc.1

update MultiSelect.svelte for Svelte5 compatibility #293

v10.3.0

8 April 2024

MultiSelect fix form validation not resetting when required prop changes #286
Update readme.md #283
Housekeeping #282
Improve docs around Events #280
Add props style, inputStyle, liOptionStyle, liSelectedStyle, ulSelectedStyle, ulOptionsStyle #279
Add props liUserMsgClass and liUserMsgActiveClass #274
link check treat 403 http status as alive, update deps 1b04c15

v10.2.0

21 September 2023

Breaking: rename focusInputOnSelect to closeDropdownOnSelect #267
Fix empty event.detail.options payload on removeAll #266
update deps 58cee43

v10.1.0

18 July 2023

Always show createOptionMsg if allowUserOptions is truthy and user entered text #254
Add key style to ObjectOption for per-option inline CSS #252
Make selected and value each reactive to each other #250
[pre-commit.ci] pre-commit autoupdate #246

v10.0.0

1 July 2023

v10.0.0 #245
Add Multiselect prop maxOptions: number #243
Add <slot name="user-msg"> #240
Rename prop duplicateFunc() to key() #238
declare types #236
add <slot name="after-input"> 0fe8e8d
add sentence on inputmode='none' use case for hiding on-screen keyboards to readme 466f0a1

v9.0.0

1 June 2023

Revert "Fix Svelte 3.57 a11y (#215)" #232
Add default slot #231
CmdPalette add prop close_keys 099e1ac
add copy buttons to all code fences 950dcf6

v8.6.2

15 May 2023

Remove circular import between MultiSelect and index.ts #230
Automatically add "bug" label to bug report issues #229
Allow createOptionMsg=null to suppress console error when allowUserOptions thruthy #227
Fix MultiSelect unable to deselect object options #226
Update pnpm instructions #224

v8.6.1

30 April 2023

Fix svelte-check errors #223
fix: hide dropdown when custom messages are empty #220
DRY workflows #218
fix: allow object options to share the same label #217
delete wait_for_animation_end() and fix tests to use playwright auto-waiting correctly 2493029
don't highlight noMatchingOptionsMsg <span> in sms-search-matches a1feca7

v8.6.0

19 March 2023

Fix Svelte 3.57 a11y #215
Add prop highlightMatches to MultiSelect #212
fix: add missing role attr for <li> #211
update deps, set TS moduleResolution=bundler a12835e

v8.5.0

9 March 2023

Fix Lighthouse a11y issues #210
clear selected and searchText first, then trigger removeAll and change events in remove_all() #208
add props style, span_style, open, dialog, input, placeholder to CmdPalette + pipe through all other props to MultiSelect 97e6815
fix /css-classes example not applying styles from external classes aa1e28e

v8.4.0

1 March 2023

Make first matching option active automatically on entering searchText #206
add src/lib/NavPalette.svelte invoked with cmd+k for keyboard-only site navigation e3f4ea9
rename NavPalette to CmdPalette and make it execute generic actions on item select b27cd80
update to svelte-package v2 8d3df3e
fix selected options having cursor: grab (to indicate drag and drop support to change order) even if only single option selected 3309e1e

v8.3.0

25 January 2023

Don't error on removing options that are in selected but not in options array #204
Add class 'remove' to buttons that remove selected options #202
Add prop allowEmpty: boolean = false #198
Support immutable Svelte compiler option #197
group demo routes e813e48
breaking: rename addOptionMsg to createOptionMsg f24e025

v8.2.4

8 January 2023

Coverage badges #190
feat: add type inference for the options prop #189
feat: add type inference for the options prop (#189) #78
merge ExampleCode.svelte with CollapsibleCode.svelte 56ff99b
pnpm add -D svelte-zoo to outsource some site components and icons f2a387c
restore reactive searchText block in loading example 846da66
fix bunch of TS errors, add playwright test for dragging selected options to reorder a483217
add update-coverage package.json script 1094f08
add vite alias $root to clean up package.json, readme|contributing|changelog.md imports c19cbe4
mv src/components src/site 3683ed7

v8.2.3

28 December 2022

add 'Open in StackBlitz' links to example code fences ac07557

v8.2.2

18 December 2022

Issue console warning if sortSelected && selectedOptionsDraggable #187
Add new slot named 'expand-icon' #186

v8.2.1

10 December 2022

Fix allowUserOptions preventing dropdown list navigation with up/down arrow keys #184
Mdsvexamples #182
Add changelog & contributing pages to site #181
tweak contributing.md and css-classes example 6f78033
fix build error b896d36
fix readme badge for gh-pages.yml status 906b560

v8.2.0

30 November 2022

Add changelog.md #180
Draggable selected options #178
Set <base href="/svelte-multiselect" /> if !dev && !prerendering #172
Publish docs to GitHub pages #170
Contributing docs plus issue and PR templates with StackBlitz repro starter #169
add missing about field to bug-report issue template (closes #171) #171
fix prop form_input: set default value null to make it optional b150fe0

v8.1.0

18 November 2022

Add minSelect prop #166
Add pnpm test to readme #168
Add class for maxSelectMsg #167
Allow required=1 | 2 | ... to set minimum number of selected options for form submission #161
Add minSelect prop (#166) #163 #163 #163
mv /max-select example to /min-max-select 9838db8

v8.0.4

15 November 2022

Form validation docs #159
Don't console.error about missing options if disabled=true #158

v8.0.3

15 November 2022

Test uncovered lines #157
Don't console.error about missing options if loading=true #156
Measure vitest coverage with c8 #155
increase --sms-min-height 19->22pt 5d0e081

v8.0.2

7 November 2022

Pass JSON.stringified selected options to form submission handlers #152
Link check CI and readme housekeeping #149
REPL links for landing page examples #148
Add Collapsible code blocks to usage examples #143
REPL links for landing page examples (#148) #144 #145 #146 #147

v8.0.1

30 October 2022

Revert SCSS preprocessing #141
Add unit tests for 2-/1-way binding of activeIndex and activeOption #139

v8.0.0

22 October 2022

Add new prop value #138
New prop resetFilterOnAdd #137
yarn to pnpm #134
Rename prop noOptionsMsg->noMatchingOptionsMsg #133
remove props selectedLabels and selectedValues ef6598e

v7.1.0

13 October 2022

Allow preventing duplicate options when allowUserOptions is thruthy #132

v7.0.2

8 October 2022

Fix TypeError: Cannot read properties of null (reading 'get_label') - take 2 #131
Fix selecting options with falsy labels (like 0) #130

v7.0.1

6 October 2022

Fix single select with arrow and enter keys #128
Add SCSS preprocessing #126
[pre-commit.ci] pre-commit autoupdate #124
more unit tests 1adbc99
test required but empty MultiSelect fails form validity check (i.e. causes unsubmittable form) and filled one passes it fd8b377

v7.0.0

3 October 2022

Make selected a single value (not a length-1 array) if maxSelect=1 #123
Fix TypeError: Cannot read properties of null (reading 'get_label') at MultiSelect.svelte:75 #122
add stopPropagation to keydown handler (closes #114) #114

v6.1.0

30 September 2022

Forward input DOM events #120
Props to manipulating inputmode and pattern attributes #116
docs: remove userInputAs prop reference #115
Fix top option not selectable with enter key #113

v6.0.3

20 September 2022

Fix using arrow keys to control active option in dropdown list #111
eslintrc set @typescript-eslint/no-inferrable-types: off c688773

v6.0.2

17 September 2022

Test readme docs on CSS variables #109
Fix selected array not being initialized to options with preselected=true #108

v6.0.1

13 September 2022

Better props docs and test #105
fix breaking change sveltekit:prefetch renamed to data-sveltekit-prefetch 65ddbb9
fix .svx demo routes fde53f1
revert from adapter-netlify to adapter-static 224144d

v6.0.0

3 September 2022

Better on mobile and better about which option is active #103
SvelteKit routes auto migration #101

v5.0.6

2 August 2022

Fix 'Cannot find module scroll-into-view-if-needed' #99

v5.0.5

2 August 2022

Add scroll-into-view-if-needed ponyfill #97

v5.0.4

17 July 2022

Convert E2E tests fromvitest to @playwright/test #95
Allow empty Multiselect #94
Add new slot 'remove-icon' #93
[pre-commit.ci] pre-commit autoupdate #92

v5.0.3

1 July 2022

Reset activeOption to null if not in matchingOptions #90

v5.0.2

27 June 2022

Replace li.scrollIntoViewIfNeeded() with li.scrollIntoView() #88
Add new prop parseLabelsAsHtml #84
try fix flaky test 'multiselect > can select and remove many options' 2b0c453
bump netlify node to v18, update readme + deps 586c724
remove plausible.js analytics cd4c9f6

v5.0.1

23 April 2022

Strongly typed custom events #79

v5.0.0

21 April 2022

v5 release #76
Work with string options as is, don't convert to objects internally #75
v5 release (#76) #57

v4.0.6

7 April 2022

Fix backspace deleting multiple selected options if identical labels #72
Several fixes for allowUserOptions #69
[pre-commit.ci] pre-commit autoupdate #70

v4.0.5

2 April 2022

Fix MultiSelect localStorage binding #66

v4.0.4

30 March 2022

Move examples to new src/routes/demos dir #63
make ToC position fixed (closes #64) #64
check for undefined (not falsy) value in rawOp processing (fixes #65) #65
LanguageSlot change SVG icons src repo to vscode-icons for more coverage 92390e9
more preselected slots in Examples.svelte cd0a01a

v4.0.3

23 March 2022

Add aria-label to hidden .form-control input #62
Add aria-label to hidden .form-control input (#62) #58 #35
fix dropdown closing when clicking between list items (closes #61) #61
svelte.config.js add kit.prerender.default: true, mv src/{global,app}.d.ts 4a84913

v4.0.2

13 March 2022

Improve a11y #60
Convert tests to Playwright #59
Convert tests to Playwright (#59) #58
add and document prop invalid (closes #47) #47
set width (not height) on svg icons and as px (not em) so they don't shrink with fluid typography on mobile screens ba77f93

v4.0.1

5 March 2022

Rename readonly to disabled #55
CSS and UX tweaks #52
Readme document test runner config to avoid transpiling errors in downstream testing #54
More tests #51
Add vitest #50
Rename readonly to disabled (#55) #45
close options dropdown list on input blur (fixes #53) #53
CSS and UX tweaks (#52) #44 #44 #44
Readme document test runner config to avoid transpiling errors in downstream testing (#54) #48

v4.0.0

21 February 2022

Implement allowUserOptions, autoScroll and loading (closes #39) #41
define DispatchEvents type used to annotate createEventDispatcher() #32
add prop required to prevent form submission if no options selected (closes #42) #42
Implement allowUserOptions, autoScroll and loading (closes #39) (#41) #39 #39

v3.3.0

20 February 2022

by default, only show maxSelectMsg if maxSelect != null and > 1 (closes #37) #37
add CSS var --sms-options-shadow defaults to subtle black shadow around dropdown list (0 0 14pt -8pt black) (closes #36) #36
add prop liActiveOptionClass = '' (closes #35) #35
turn searchText = and showOptions = false into bindable props (closes #33) #33
document missing noOptionsMsg prop (closes #34) #34
ensure custom class names (outerDivClass, ulOptionsClass) come last (closes #38) #38
fix ToC scroll to heading (closes #31) #31
only show remove all btn when maxSelect !== 1 (for #37) 64cfd8a

v3.2.3

19 February 2022

Fixes for focus on click and wiggle on hitting maxSelect #30

v3.2.2

16 February 2022

Expose filter method #29
readme improve docs on css variables and granular control through :global() selectors (closes #27) #27

v3.2.1

7 February 2022

mv input outside ul.selected for better HTML semantics (closes #26) #26

v3.2.0

3 February 2022

apply id prop to <input> insted of outer div (closes #25) #25
add eslint commit hook + update deps 6ad44b8
v.3.2.0 71ff2d1
add readme badge to document minimum svelte version (for #24) 7d9fe5a

v3.1.1

25 January 2022

wiggle the maxSelect msg on hitting selection limit (closes #19) #19
readme better docs for CSS variables, rename slots {options,selected}Renderer -> render{options,selected} c8ab724

v3.1.0

22 January 2022

add selectedRenderer + optionRenderer named slots (closes #21) #21
docs site use unmodified readme with slot to insert examples, yarn add svelte-github-corner 1072691
readme add note on type exports for TS users, add error page that redirects to index dde76c8

v3.0.1

7 January 2022

favorite web framework show Confetti.svelte on:add Svelte 8d109ee
bump svelte@3.45.0 to silence warning: MultiSelect has unused export property 'defaultDisabledTitle' (sveltejs/svelte#6964) f80a7a6
update readme + svelte-toc@0.2.0 40013ba
[pre-commit.ci] pre-commit autoupdate 0d05864
iOS Safari prevent zoom into page on focus MultiSelect input 44f17be

v3.0.0

29 December 2021

ensure active option is scrolled into view if needed (closes #15), breaking change: renames tokens to options #15

v2.0.0

24 December 2021

Convert options from simple strings to objects #16
Add local to transition:fly #14
add onClickOutside action, used to replace input.on:blur() for hiding options (closes #18) #18
update deps fb90f93
more keyboard friendliness by showing remove button focus and triggering on space bar or enter key b87d22b
add plausible 0557c0f

v1.2.2

27 October 2021

set <input> width back to 1pt as it's only needed to tab into, focus and blur <MultiSelect> (closes #12) #12
update readme 45c7993

v1.2.1

21 October 2021

make internal CSS easily overridable (sveltejs/svelte#6859) d15a445

v1.2.0

12 October 2021

add src/lib/index.ts for package path export '.' (closes #11) #11

v1.1.13

12 October 2021

add src/lib/index.ts for package path export '.' (closes #11) #11

v1.1.12

11 October 2021

Add new prop disabledOptions #9
add pre-commit hooks dfb6399
[pre-commit.ci] pre-commit autoupdate b69425d

v1.1.11

3 September 2021

fix removeAll button not dispatching remove and change events (closes #7) #7
remove @tsconfig/svelte, update deps 9b2c231
add type=(add|remove) detail to 'change' event dispatch 8290458

v1.1.10

12 August 2021

add on:change event and document events in readme (closes #5) #5

v1.1.9

12 July 2021

convert to typescript bd391c5
update to @sveltejs/kit@1.0.0-next.124+ to use svelte field in package.json 2367e38

v1.1.8

7 July 2021

turn hard-coded remove button titles into props c35162b
guard against selected being nullish, keep ul.options in the DOM even if showoptions is false to allow selecting in dev tools for styling b9bd576

v1.1.7

5 July 2021

add css classes as props for use with tailwind (closes #3) #3

v1.1.6

23 June 2021

fix: don't remove tags if search string is non-empty, open options on clicking selected tags (#2) 5ffed50
update svelte-toc to fix deploy d5279dd

v1.1.5

22 June 2021

convert to svelte-kit package 9db3cfb

v1.1.4

21 June 2021

fix setting initial value for selected, fix setting class 'selected' in single mode 16d11de

v1.1.3

20 June 2021

replace prop single with maxSelect to specify any number of selectable options, add class single to div.multiselect if maxSelect===1 (#2) 36e916f
add linked headings 2eedf9a

v1.1.2

28 May 2021

add css var props f591814

v1.1.1

25 May 2021

add GitHubCorner.svelte for link to repo e80a402
remove selected tokens with backspace c5d7495
add readme badges 992eaa4
demo site fix stripping start of readme for docs 107273d
add svelte-toc table of contents to demo site 36aa1c5

v1.1.0

9 May 2021

import readme on demo site instead of duplication c0e4924
remove ununsed example.svx 2138caa
rename package dir, improve readme 0150378

v1.0.1

8 May 2021

remove hidden input for storing currently selected as JSON 802a219

v1.0.0

7 May 2021

initial commit 14dd38a