svelte-multiselect 2.0.0 → 3.1.1

package/MultiSelect.svelte

@@ -2,6 +2,7 @@
 import { fly } from 'svelte/transition';
 import { onClickOutside } from './actions';
 import { CrossIcon, ExpandIcon, ReadOnlyIcon } from './icons';
+import Wiggle from './Wiggle.svelte';
 export let selected = [];
 export let selectedLabels = [];
 export let selectedValues = [];
@@ -16,12 +17,13 @@ export let id = undefined;
 export let noOptionsMsg = `No matching options`;
 export let activeOption = null;
 export let outerDivClass = ``;
-export let ulTokensClass = ``;
-export let liTokenClass = ``;
+export let ulSelectedClass = ``;
+export let liSelectedClass = ``;
 export let ulOptionsClass = ``;
 export let liOptionClass = ``;
 export let removeBtnTitle = `Remove`;
 export let removeAllTitle = `Remove all`;
+// https://github.com/sveltejs/svelte/issues/6964
 export let defaultDisabledTitle = `This option is disabled`;
 if (maxSelect !== null && maxSelect < 0) {
     console.error(`maxSelect must be null or positive integer, got ${maxSelect}`);
@@ -30,12 +32,13 @@ if (!(options?.length > 0))
     console.error(`MultiSelect missing options`);
 if (!Array.isArray(selected))
     console.error(`selected prop must be an array`);
-function isObject(item) {
-    return typeof item === `object` && !Array.isArray(item) && item !== null;
-}
 onMount(() => {
     selected = _options.filter((op) => op?.preselected);
 });
+let wiggle = false;
+function isObject(item) {
+    return typeof item === `object` && !Array.isArray(item) && item !== null;
+}
 // process proto options to full ones with mandatory labels
 $: _options = options.map((rawOp) => {
     // convert to objects internally if user passed list of strings or numbers as options
@@ -78,35 +81,37 @@ $: if (
     // make the first filtered option active
     activeOption = matchingEnabledOptions[0];
 function add(label) {
+    if (selected.length - (maxSelect ?? 0) < 1)
+        wiggle = true;
     if (!readonly &&
         !selectedLabels.includes(label) &&
-        // for maxselect = 1 we always replace current token with new selection
+        // for maxselect = 1 we always replace current option with new selection
         (maxSelect == null || maxSelect == 1 || selected.length < maxSelect)) {
         searchText = ``; // reset search string on selection
-        const token = _options.find((op) => op.label === label);
-        if (!token) {
+        const option = _options.find((op) => op.label === label);
+        if (!option) {
             console.error(`MultiSelect: option with label ${label} not found`);
             return;
         }
         if (maxSelect === 1) {
-            selected = [token];
+            selected = [option];
         }
         else {
-            selected = [token, ...selected];
+            selected = [option, ...selected];
         }
         if (selected.length === maxSelect)
             setOptionsVisible(false);
-        dispatch(`add`, { token });
-        dispatch(`change`, { token, type: `add` });
+        dispatch(`add`, { option });
+        dispatch(`change`, { option, type: `add` });
     }
 }
 function remove(label) {
     if (selected.length === 0 || readonly)
         return;
-    selected = selected.filter((token) => label !== token.label);
-    const token = _options.find((option) => option.label === label);
-    dispatch(`remove`, { token });
-    dispatch(`change`, { token, type: `remove` });
+    selected = selected.filter((option) => label !== option.label);
+    const option = _options.find((option) => option.label === label);
+    dispatch(`remove`, { option });
+    dispatch(`change`, { option, type: `remove` });
 }
 function setOptionsVisible(show) {
     // nothing to do if visibility is already as intended
@@ -130,9 +135,7 @@ function handleKeydown(event) {
     // on enter key: toggle active option and reset search text
     else if (event.key === `Enter`) {
         if (activeOption) {
-            const { label, disabled } = activeOption;
-            if (disabled)
-                return;
+            const { label } = activeOption;
             selectedLabels.includes(label) ? remove(label) : add(label);
             searchText = ``;
         } // no active option means the options dropdown is closed in which case enter means open it
@@ -148,17 +151,30 @@ function handleKeydown(event) {
         }
         const increment = event.key === `ArrowUp` ? -1 : 1;
         const newActiveIdx = matchingEnabledOptions.indexOf(activeOption) + increment;
+        const ulOps = document.querySelector(`ul.options`);
         if (newActiveIdx < 0) {
             // wrap around top
             activeOption = matchingEnabledOptions[matchingEnabledOptions.length - 1];
-            // wrap around bottom
+            if (ulOps)
+                ulOps.scrollTop = ulOps.scrollHeight;
         }
         else if (newActiveIdx === matchingEnabledOptions.length) {
+            // wrap around bottom
             activeOption = matchingEnabledOptions[0];
-            // default case
+            if (ulOps)
+                ulOps.scrollTop = 0;
         }
-        else
+        else {
+            // default case
             activeOption = matchingEnabledOptions[newActiveIdx];
+            const li = document.querySelector(`ul.options > li.active`);
+            // scrollIntoViewIfNeeded() scrolls top edge of element into view so when moving
+            // downwards, we scroll to next sibling to make element fully visible
+            if (increment === 1)
+                li?.nextSibling?.scrollIntoViewIfNeeded();
+            else
+                li?.scrollIntoViewIfNeeded();
+        }
     }
     else if (event.key === `Backspace`) {
         const label = selectedLabels.pop();
@@ -167,8 +183,8 @@ function handleKeydown(event) {
     }
 }
 const removeAll = () => {
-    dispatch(`remove`, { token: selected });
-    dispatch(`change`, { token: selected, type: `remove` });
+    dispatch(`removeAll`, { options: selected });
+    dispatch(`change`, { options: selected, type: `removeAll` });
     selected = [];
     searchText = ``;
 };
@@ -181,7 +197,7 @@ const handleEnterAndSpaceKeys = (handler) => (event) => {
 };
 </script>
 
-<!-- z-index: 2 when showOptions is true ensures the ul.tokens of one <MultiSelect />
+<!-- z-index: 2 when showOptions is true ensures the ul.selected of one <MultiSelect />
 display above those of another following shortly after it -->
 <div
   {id}
@@ -194,31 +210,24 @@ display above those of another following shortly after it -->
   use:onClickOutside={() => dispatch(`blur`)}
 >
   <ExpandIcon height="14pt" style="padding: 0 3pt 0 1pt;" />
-  <ul class="tokens {ulTokensClass}">
-    {#if maxSelect == 1 && selected[0]?.label}
-      <span on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}>
-        {selected[0].label}
-      </span>
-    {:else}
-      {#each selected as { label }}
-        <li
-          class={liTokenClass}
-          on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}
-        >
-          {label}
-          {#if !readonly}
-            <button
-              on:mouseup|stopPropagation={() => remove(label)}
-              on:keydown={handleEnterAndSpaceKeys(() => remove(label))}
-              type="button"
-              title="{removeBtnTitle} {label}"
-            >
-              <CrossIcon height="12pt" />
-            </button>
-          {/if}
-        </li>
-      {/each}
-    {/if}
+  <ul class="selected {ulSelectedClass}">
+    {#each selected as option, idx}
+      <li class={liSelectedClass}>
+        <slot name="renderSelected" {option} {idx}>
+          {option.label}
+        </slot>
+        {#if !readonly}
+          <button
+            on:mouseup|stopPropagation={() => remove(option.label)}
+            on:keydown={handleEnterAndSpaceKeys(() => remove(option.label))}
+            type="button"
+            title="{removeBtnTitle} {option.label}"
+          >
+            <CrossIcon height="12pt" />
+          </button>
+        {/if}
+      </li>
+    {/each}
     <input
       bind:this={input}
       autocomplete="off"
@@ -234,7 +243,9 @@ display above those of another following shortly after it -->
     <ReadOnlyIcon height="14pt" />
   {:else if selected.length > 0}
     {#if maxSelect !== null && maxSelect > 1}
-      <span style="padding: 0 3pt;">{maxSelectMsg(selected.length, maxSelect)}</span>
+      <Wiggle bind:wiggle angle={20}>
+        <span style="padding: 0 3pt;">{maxSelectMsg(selected.length, maxSelect)}</span>
+      </Wiggle>
     {/if}
     <button
       type="button"
@@ -253,7 +264,9 @@ display above those of another following shortly after it -->
       class:hidden={!showOptions}
       transition:fly|local={{ duration: 300, y: 40 }}
     >
-      {#each matchingOptions as { label, disabled, title = '', selectedTitle, disabledTitle = defaultDisabledTitle }}
+      {#each matchingOptions as option, idx}
+        {@const { label, disabled, title = null, selectedTitle } = option}
+        {@const { disabledTitle = defaultDisabledTitle } = option}
         <li
           on:mouseup|preventDefault|stopPropagation
           on:mousedown|preventDefault|stopPropagation={() => {
@@ -266,7 +279,9 @@ display above those of another following shortly after it -->
           title={disabled ? disabledTitle : (isSelected(label) && selectedTitle) || title}
           class={liOptionClass}
         >
-          {label}
+          <slot name="renderOptions" {option} {idx}>
+            {option.label}
+          </slot>
         </li>
       {:else}
         {noOptionsMsg}
@@ -276,26 +291,28 @@ display above those of another following shortly after it -->
 </div>
 
 <style>
-  :where(.multiselect) {
+  :where(div.multiselect) {
     position: relative;
     margin: 1em 0;
     border: var(--sms-border, 1pt solid lightgray);
     border-radius: var(--sms-border-radius, 5pt);
+    background: var(--sms-input-bg);
+    height: var(--sms-input-height, 2em);
     align-items: center;
     min-height: 18pt;
     display: flex;
     cursor: text;
     padding: 0 3pt;
   }
-  :where(.multiselect:focus-within) {
+  :where(div.multiselect:focus-within) {
     border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue));
   }
-  :where(.multiselect.readonly) {
+  :where(div.multiselect.readonly) {
     background: var(--sms-readonly-bg, lightgray);
   }
 
-  :where(ul.tokens > li) {
-    background: var(--sms-token-bg, var(--sms-active-color, cornflowerblue));
+  :where(ul.selected > li) {
+    background: var(--sms-selected-bg, var(--sms-active-color, cornflowerblue));
     align-items: center;
     border-radius: 4pt;
     display: flex;
@@ -305,7 +322,7 @@ display above those of another following shortly after it -->
     white-space: nowrap;
     height: 16pt;
   }
-  :where(ul.tokens > li button, button.remove-all) {
+  :where(ul.selected > li button, button.remove-all) {
     align-items: center;
     border-radius: 50%;
     display: flex;
@@ -320,29 +337,32 @@ display above those of another following shortly after it -->
     outline: none;
     padding: 0 2pt;
   }
-  :where(ul.tokens > li button:hover, button.remove-all:hover) {
+  :where(ul.selected > li button:hover, button.remove-all:hover, button:focus) {
     color: var(--sms-remove-x-hover-focus-color, lightskyblue);
   }
   :where(button:focus) {
-    color: var(--sms-remove-x-hover-focus-color, lightskyblue);
     transform: scale(1.04);
   }
 
-  :where(.multiselect input) {
+  :where(div.multiselect input) {
     border: none;
     outline: none;
     background: none;
     color: var(--sms-text-color, inherit);
     flex: 1; /* this + next line fix issue #12 https://git.io/JiDe3 */
     min-width: 2em;
+    /* minimum font-size > 16px ensures iOS doesn't zoom in when focusing input */
+    /* https://stackoverflow.com/a/6394497 */
+    font-size: calc(16px + 0.1vw);
   }
 
-  :where(ul.tokens) {
+  :where(ul.selected) {
     display: flex;
     padding: 0;
     margin: 0;
     flex-wrap: wrap;
     flex: 1;
+    overscroll-behavior: none;
   }
 
   :where(ul.options) {

package/MultiSelect.svelte.d.ts

@@ -16,8 +16,8 @@ declare const __propDef: {
         noOptionsMsg?: string | undefined;
         activeOption?: Option | null | undefined;
         outerDivClass?: string | undefined;
-        ulTokensClass?: string | undefined;
-        liTokenClass?: string | undefined;
+        ulSelectedClass?: string | undefined;
+        liSelectedClass?: string | undefined;
         ulOptionsClass?: string | undefined;
         liOptionClass?: string | undefined;
         removeBtnTitle?: string | undefined;
@@ -29,7 +29,16 @@ declare const __propDef: {
     } & {
         [evt: string]: CustomEvent<any>;
     };
-    slots: {};
+    slots: {
+        renderSelected: {
+            option: Option;
+            idx: any;
+        };
+        renderOptions: {
+            option: Option;
+            idx: any;
+        };
+    };
 };
 export declare type MultiSelectProps = typeof __propDef.props;
 export declare type MultiSelectEvents = typeof __propDef.events;

package/Wiggle.svelte

@@ -0,0 +1,24 @@
+<script >import { spring } from 'svelte/motion';
+// bind to this state and set it to true from parent
+export let wiggle = false;
+// intended use case: set max value during wiggle for one of angle, scale, dx, dy through props
+export let angle = 0; // try 20
+export let scale = 1; // try 1.2
+export let dx = 0; // try 10
+export let dy = 0; // try 10
+export let duration = 200;
+export let stiffness = 0.05;
+export let damping = 0.1;
+let restState = { angle: 0, scale: 1, dx: 0, dy: 0 };
+let store = spring(restState, { stiffness, damping });
+$: store.set(wiggle ? { scale, angle, dx, dy } : restState);
+$: if (wiggle)
+    setTimeout(() => (wiggle = false), duration);
+</script>
+
+<span
+  style:transform="rotate({$store.angle}deg) scale({$store.scale}) translate({$store.dx}px,
+  {$store.dy}px)"
+>
+  <slot />
+</span>

package/Wiggle.svelte.d.ts

@@ -0,0 +1,25 @@
+import { SvelteComponentTyped } from "svelte";
+declare const __propDef: {
+    props: {
+        wiggle?: boolean | undefined;
+        angle?: number | undefined;
+        scale?: number | undefined;
+        dx?: number | undefined;
+        dy?: number | undefined;
+        duration?: number | undefined;
+        stiffness?: number | undefined;
+        damping?: number | undefined;
+    };
+    events: {
+        [evt: string]: CustomEvent<any>;
+    };
+    slots: {
+        default: {};
+    };
+};
+export declare type WiggleProps = typeof __propDef.props;
+export declare type WiggleEvents = typeof __propDef.events;
+export declare type WiggleSlots = typeof __propDef.slots;
+export default class Wiggle extends SvelteComponentTyped<WiggleProps, WiggleEvents, WiggleSlots> {
+}
+export {};

package/package.json

@@ -5,33 +5,32 @@
   "homepage": "https://svelte-multiselect.netlify.app",
   "repository": "https://github.com/janosh/svelte-multiselect",
   "license": "MIT",
-  "version": "2.0.0",
+  "version": "3.1.1",
   "type": "module",
-  "svelte": "MultiSelect.svelte",
-  "bugs": {
-    "url": "https://github.com/janosh/svelte-multiselect/issues"
-  },
+  "svelte": "index.js",
+  "bugs": "https://github.com/janosh/svelte-multiselect/issues",
   "devDependencies": {
-    "@sveltejs/adapter-static": "^1.0.0-next.22",
-    "@sveltejs/kit": "^1.0.0-next.202",
-    "@typescript-eslint/eslint-plugin": "^5.7.0",
-    "@typescript-eslint/parser": "^5.7.0",
-    "eslint": "^8.5.0",
-    "eslint-plugin-svelte3": "^3.2.1",
+    "@sveltejs/adapter-static": "^1.0.0-next.26",
+    "@sveltejs/kit": "^1.0.0-next.239",
+    "@typescript-eslint/eslint-plugin": "^5.10.0",
+    "@typescript-eslint/parser": "^5.10.0",
+    "eslint": "^8.7.0",
+    "eslint-plugin-svelte3": "^3.4.0",
     "hastscript": "^7.0.2",
     "mdsvex": "^0.9.8",
     "prettier": "^2.5.1",
-    "prettier-plugin-svelte": "^2.5.1",
-    "rehype-autolink-headings": "^6.1.0",
-    "rehype-slug": "^5.0.0",
-    "svelte": "^3.44.3",
-    "svelte-check": "^2.2.11",
-    "svelte-preprocess": "^4.10.1",
-    "svelte-toc": "^0.1.10",
-    "svelte2tsx": "^0.4.12",
+    "prettier-plugin-svelte": "^2.6.0",
+    "rehype-autolink-headings": "^6.1.1",
+    "rehype-slug": "^5.0.1",
+    "svelte": "^3.46.2",
+    "svelte-check": "^2.3.0",
+    "svelte-github-corner": "^0.1.0",
+    "svelte-preprocess": "^4.10.2",
+    "svelte-toc": "^0.2.2",
+    "svelte2tsx": "^0.4.14",
     "tslib": "^2.3.1",
-    "typescript": "^4.5.4",
-    "vite": "^2.7.3"
+    "typescript": "^4.5.5",
+    "vite": "^2.7.13"
   },
   "keywords": [
     "svelte",
@@ -46,7 +45,6 @@
   "exports": {
     "./package.json": "./package.json",
     "./MultiSelect.svelte": "./MultiSelect.svelte",
-    "./actions": "./actions.js",
     ".": "./index.js"
   }
 }

package/readme.md

@@ -1,10 +1,7 @@
-<div class="maybe-hide">
-
-<p align="center">
-  <img src="static/favicon.svg" alt="Svelte MultiSelect" height=80>
-</p>
-
-<h1 align="center">Svelte MultiSelect</h1>
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/janosh/svelte-toc/main/static/favicon.svg" alt="Svelte MultiSelect" height=60>
+  <br>&ensp;Svelte MultiSelect
+</h1>
 
 <h4 align="center">
 
@@ -14,25 +11,39 @@
 
 </h4>
 
+<div class="hide-in-docs">
+
 **[Live demo](https://svelte-multiselect.netlify.app)**.
 
 </div>
 
-<!-- remove above in docs -->
-
 **Keyboard-friendly, zero-dependency multi-select Svelte component.**
 
+<slot />
+
 ## 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 within the text input
+- **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
+
+- v2.0.0 added the ability to pass options as objects. As a result, `bind:selected` no longer returns simple strings but objects, even if you still pass in `options` as strings. To get the same stuff you would have gotten from `bind:selected` before, there's now `bind:selectedLabels` (and `bind:selectedValues`).
+- 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.0.0
+  on:add={(e) => console.log(e.detail.option.label)} // v3.0.0
+  ```
+
+  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`.
+
 ## Installation
 
 ```sh
@@ -93,53 +104,118 @@ Full list of props/bindable variables for this component:
 
 </div>
 
+## Slots
+
+`MultiSelect.svelte` accepts two named slots
+
+- `slot="renderOptions"`
+- `slot="renderSelected"`
+
+to customize rendering individual options in the dropdown and the list of selected tags, respectively. Each renderer receives the full `option` object along with the zero-indexed position (`idx`) in its list, both available via the `let:` directive:
+
+```svelte
+<MultiSelect options={[`Banana`, `Apple`, `Mango`]}>
+  <span let:idx let:option slot="renderOptions">
+    {idx + 1}. {option.label}
+    {option.label === `Mango` ? `🎉` : ``}
+  </span>
+
+  <span let:idx let:option slot="renderSelected">
+    #{idx + 1}
+    {option.label}
+  </span>
+</MultiSelect>
+```
+
 ## Events
 
 `MultiSelect.svelte` dispatches the following events:
 
-| name     | details                         | description                                                                                                                                    |
-| -------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `add`    | `token: string`                 | Triggers when a new token is selected.                                                                                                         |
-| `remove` | `token: string`                 | Triggers when one or all selected tokens are removed. `event.detail.token` will be a single or multiple tokens, respectively.                  |
-| `change` | `token: string`, `type: string` | Triggers when a token is either added or removed, or all tokens are removed at once. `event.detail.type` will be either `'add'` or `'remove'`. |
-| `blur`   | none                            | Triggers when the input field looses focus.                                                                                                    |
+| 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`    | `{ option?: Option, options?: Option[] }`, `type: 'add' \| 'remove' \| 'removeAll'` | Triggers when a option is either added or removed, or all options are removed at once.                                              |
+| `blur`      | none                                                                                | Triggers when the input field looses focus.                                                                                         |
 
 ### Examples
 
 <!-- prettier-ignore -->
-- `on:add={(event) => console.log(event.detail.token.label)}`
-- `on:remove={(event) => console.log(event.detail.token.label)}`.
-- ``on:change={(event) => console.log(`${event.detail.type}: '${event.detail.token.label}'`)}``
+- `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
 <MultiSelect
-  on:change={(e) => alert(`You ${e.detail.type}ed '${e.detail.token.label}'`)}
+  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:
+
+```svelte
+<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.
+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
+<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
 
-The first, if you only want to make small adjustments, allows you to pass the following CSS variables directly to the component as props.
-
-- `border: var(--sms-border, 1pt solid lightgray)`: Border around top-level `div.multiselect`. 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, 5pt)`: `div.multiselect` border radius.
-- `color: var(--sms-text-color, inherit)`: Input text color.
-- `border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue))`: `div.multiselect` border when focused. Falls back to `--sms-active-color` if not set which in turn falls back on `cornflowerblue`.
-- `background: var(--sms-readonly-bg, lightgray)`: Background when in readonly state.
-- `background: var(--sms-token-bg, var(--sms-active-color, cornflowerblue))`: Background of selected tokens.
-- `color: var(--sms-remove-x-hover+focus-color, lightgray)`: Hover color of cross icon to remove selected tokens.
-- `color: var(--sms-remove-x-hover-focus-color, lightskyblue)`: Color of the cross-icon buttons for removing all or individual selected options when in `:focus` or `:hover` state.
-- `background: var(--sms-options-bg, white)`: Background of options list.
-- `background: var(--sms-li-selected-bg, inherit)`: Background of selected list items in options pane.
-- `color: var(--sms-li-selected-color, inherit)`: Text color of selected list items in options pane.
-- `background: var(--sms-li-active-bg, var(--sms-active-color, cornflowerblue))`: Background of active (currently with arrow keys highlighted) list item.
-- `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.
+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, 5pt)`: Input border radius.
+  - `background: var(--sms-input-bg)`: Input background.
+  - `height: var(--sms-input-height, 2em)`: Input height.
+  - `border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue))`: Border when focused. Falls back to `--sms-active-color` if not set which in turn falls back on `cornflowerblue`.
+  - `background: var(--sms-readonly-bg, lightgray)`: Background when in readonly state.
+- `div.multiselect input`
+  - `color: var(--sms-text-color, inherit)`: Input text color.
+- `ul.selected > li`:
+  - `background: var(--sms-selected-bg, var(--sms-active-color, cornflowerblue))`: Background of selected options.
+- `ul.selected > li button:hover, button.remove-all:hover`
+  - `color: var(--sms-remove-x-hover-focus-color, lightskyblue)`: Color of the cross-icon buttons for removing all or individual selected options when in `:focus` or `:hover` state.
+- `ul.options`
+  - `background: var(--sms-options-bg, white)`: Background of options list.
+- `ul.options > li.selected`
+  - `background: var(--sms-li-selected-bg, inherit)`: Background of selected list items in options pane.
+  - `color: var(--sms-li-selected-color, inherit)`: Text color of selected list items in options pane.
+- `ul.options > li.active`
+  - `background: var(--sms-li-active-bg, var(--sms-active-color, cornflowerblue))`: Background of active (currently with arrow keys highlighted) list item.
+- `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:
 
@@ -152,38 +228,38 @@ For example, to change the background color of the options dropdown:
 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](https://tailwindcss.com).
 
 - `outerDivClass`
-- `ulTokensClass`
-- `liTokenClass`
+- `ulSelectedClass`
+- `liSelectedClass`
 - `ulOptionsClass`
 - `liOptionClass`
 
 This simplified version of the DOM structure of this component shows where these classes are inserted:
 
 ```svelte
-<div class={outerDivClass}>
-  <ul class={ulTokensClass}>
-    <li class={liTokenClass}>First selected tag</li>
-    <li class={liTokenClass}>Second selected tag</li>
+<div class="multiselect {outerDivClass}">
+  <ul class="selected {ulSelectedClass}">
+    <li class={liSelectedClass}>Selected 1</li>
+    <li class={liSelectedClass}>Selected 2</li>
   </ul>
-  <ul class={ulOptionsClass}>
-    <li class={liOptionClass}>First available option</li>
-    <li class={liOptionClass}>Second available option</li>
+  <ul class="options {ulOptionsClass}">
+    <li class={liOptionClass}>Option 1</li>
+    <li class={liOptionClass}>Option 2</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.tokens` 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.
+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.
 
 ```css
 :global(.multiselect) {
   /* top-level wrapper div */
 }
-:global(.multiselect ul.tokens > li) {
+:global(.multiselect ul.selected > li) {
   /* selected options */
 }
-:global(.multiselect ul.tokens > li button),
+:global(.multiselect ul.selected > li button),
 :global(.multiselect button.remove-all) {
   /* buttons to remove a single or all selected options at once */
 }