svelte-multiselect-new v4.0.7

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
• 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.

  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: <slot name="renderOptions" />, new: <slot name="option" />
  • old: <slot name="renderSelected" />, new: <slot name="selected" />

• 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 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-<attr> were renamed to just --sms-<attr>. E.g. --sms-input-min-height is now --sms-min-height.

Installation

yarn add -D svelte-multiselect

Usage

<script>
  import MultiSelect from 'svelte-multiselect'

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

  let selected = []
</script>

Favorite Frontend Frameworks?

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

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

Props

Full list of props/bindable variables for this component:

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:

   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:

   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 <span slot="disabled-icon" /> or div to remove the default disabled icon.

Example:

<MultiSelect options={[`Red`, `Green`, `Blue`, `Yellow`, `Purple`]}>
  <span let:idx let:option slot="option">
    {idx + 1}
    {option.label}
    <span style:background={option.label} style=" width: 1em; height: 1em;" />
  </span>

  <span let:idx let:option slot="selected">
    {idx + 1}
    {option.label}
    <span style:background={option.label} style=" width: 1em; height: 1em;" />
  </span>

  <CustomSpinner slot="spinner">
</MultiSelect>

Events

MultiSelect.svelte dispatches the following events:

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}

<MultiSelect
  on:change={(e) => alert(`You ${e.detail.type}ed '${e.detail.option.label}'`)}
/>

TypeScript

TypeScript users can import the types used for internal type safety:

<script lang="ts">
  import MultiSelect, {
    Option,
    Primitive,
    ProtoOption,
  } from 'svelte-multiselect'

  const myOptions: Option[] = [
    { label: 'foo', value: 42 },
    { label: 'bar', value: 69 },
  ]
</script>

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.

• 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)
  • max-width: var(--sms-max-width)
• 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 if not set which 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)
• 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, 5pt 1pt): 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-button-hover-color, lightskyblue): Color of the cross-icon buttons for removing all or individual selected options when in :focus or :hover state.
• 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.
• 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 dropdown item. Items become active either by mouseover or by navigating to them with arrow keys.
• 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.

For example, to change the background color of the options dropdown:

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

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
• ulSelectedClass
• liSelectedClass
• ulOptionsClass
• liOptionClass
• liActiveOptionClass

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>
  <ul class="options {ulOptionsClass}">
    <li class={liOptionClass}>Option 1</li>
    <li class="{liOptionClass} {liActiveOptionClass}">
      Option 2 (currently active)
    </li>
  </ul>
</div>

Granular control through global CSS

You can alternatively style every part of this component with more fine-grained control 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 has focus.

: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 > ul.selected > li > input) {
  /* 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) */
}

Downstream testing

To test a Svelte component which imports svelte-multiselect, you need to configure your test runner to avoid transpiling issues.

For Jest, exclude svelte-multiselect from transformIgnorePatterns in your jest.config.json:

{
  "transformIgnorePatterns": ["node_modules/?!(svelte-multiselect)"],
  "transform": {
    "^.+\\.[t|j]s?$": "esbuild-jest",
    "^.+\\.svelte$": ["svelte-jester", { "preprocess": true }]
  }
}

For Vitest, include svelte-multiselect in deps.inline:

// vite.config.ts
import { svelte } from '@sveltejs/vite-plugin-svelte'

export default {
  plugins: [svelte({ hot: !process.env.VITEST })],
  test: {
    deps: {
      inline: [/svelte-multiselect/],
    },
  },
}

Here's a Stackblitz example that also uses vitest-svelte-kit.

Want to contribute?

To submit a PR, clone the repo, install dependencies and start the dev server to try out your changes.

git clone https://github.com/janosh/svelte-multiselect
cd svelte-multiselect
yarn
yarn dev