svelte-multiselect 3.1.0 → 3.2.2

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 = [];
@@ -11,10 +12,15 @@ export let readonly = false;
 export let options;
 export let input = null;
 export let placeholder = undefined;
-export let name = undefined;
 export let id = undefined;
+export let name = id;
 export let noOptionsMsg = `No matching options`;
 export let activeOption = null;
+export let filterFunc = (op, searchText) => {
+    if (!searchText)
+        return true;
+    return `${op.label}`.toLowerCase().includes(searchText.toLowerCase());
+};
 export let outerDivClass = ``;
 export let ulSelectedClass = ``;
 export let liSelectedClass = ``;
@@ -34,6 +40,7 @@ if (!Array.isArray(selected))
 onMount(() => {
     selected = _options.filter((op) => op?.preselected);
 });
+let wiggle = false;
 function isObject(item) {
     return typeof item === `object` && !Array.isArray(item) && item !== null;
 }
@@ -64,11 +71,7 @@ const dispatch = createEventDispatcher();
 let searchText = ``;
 let showOptions = false;
 // options matching the current search text
-$: matchingOptions = _options.filter((op) => {
-    if (!searchText)
-        return true;
-    return `${op.label}`.toLowerCase().includes(searchText.toLowerCase());
-});
+$: matchingOptions = _options.filter((op) => filterFunc(op, searchText));
 $: matchingEnabledOptions = matchingOptions.filter((op) => !op.disabled);
 $: if (
 // if there was an active option but it's not in the filtered list of options
@@ -79,6 +82,8 @@ $: 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 option with new selection
@@ -196,11 +201,10 @@ const handleEnterAndSpaceKeys = (handler) => (event) => {
 <!-- 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}
   class="multiselect {outerDivClass}"
   class:readonly
   class:single={maxSelect == 1}
-  style={showOptions ? `z-index: 2;` : undefined}
+  class:open={showOptions}
   on:mouseup|stopPropagation={() => setOptionsVisible(true)}
   use:onClickOutside={() => setOptionsVisible(false)}
   use:onClickOutside={() => dispatch(`blur`)}
@@ -209,7 +213,7 @@ display above those of another following shortly after it -->
   <ul class="selected {ulSelectedClass}">
     {#each selected as option, idx}
       <li class={liSelectedClass}>
-        <slot name="selectedRenderer" {option} {idx}>
+        <slot name="renderSelected" {option} {idx}>
           {option.label}
         </slot>
         {#if !readonly}
@@ -224,22 +228,25 @@ display above those of another following shortly after it -->
         {/if}
       </li>
     {/each}
-    <input
-      bind:this={input}
-      autocomplete="off"
-      bind:value={searchText}
-      on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}
-      on:keydown={handleKeydown}
-      on:focus={() => setOptionsVisible(true)}
-      {name}
-      placeholder={selectedLabels.length ? `` : placeholder}
-    />
   </ul>
+  <input
+    bind:this={input}
+    autocomplete="off"
+    bind:value={searchText}
+    on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}
+    on:keydown={handleKeydown}
+    on:focus={() => setOptionsVisible(true)}
+    {id}
+    {name}
+    placeholder={selectedLabels.length ? `` : placeholder}
+  />
   {#if readonly}
     <ReadOnlyIcon height="14pt" />
   {:else if selected.length > 0}
-    {#if maxSelect !== null && maxSelect > 1}
-      <span style="padding: 0 3pt;">{maxSelectMsg(selected.length, maxSelect)}</span>
+    {#if maxSelect !== null && maxSelectMsg !== null}
+      <Wiggle bind:wiggle angle={20}>
+        <span style="padding: 0 3pt;">{maxSelectMsg(selected.length, maxSelect)}</span>
+      </Wiggle>
     {/if}
     <button
       type="button"
@@ -273,55 +280,66 @@ display above those of another following shortly after it -->
           title={disabled ? disabledTitle : (isSelected(label) && selectedTitle) || title}
           class={liOptionClass}
         >
-          <slot name="optionRenderer" {option} {idx}>
+          <slot name="renderOptions" {option} {idx}>
             {option.label}
           </slot>
         </li>
       {:else}
-        {noOptionsMsg}
+        <span>{noOptionsMsg}</span>
       {/each}
     </ul>
   {/key}
 </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);
     align-items: center;
     min-height: 18pt;
     display: flex;
     cursor: text;
     padding: 0 3pt;
+    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);
+  }
+  :where(div.multiselect.open) {
+    z-index: var(--sms-open-z-index, 4);
   }
-  :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.selected > li) {
-    background: var(--sms-selected-bg, var(--sms-active-color, cornflowerblue));
+  :where(div.multiselect > ul.selected) {
+    display: flex;
+    padding: 0;
+    margin: 0;
+    flex-wrap: wrap;
+  }
+  :where(div.multiselect > ul.selected > li) {
     align-items: center;
     border-radius: 4pt;
     display: flex;
     margin: 2pt;
-    padding: 0 0 0 1ex;
+    padding: 0 0 0 5pt;
     transition: 0.3s;
     white-space: nowrap;
-    height: 16pt;
+    background: var(--sms-selected-bg, var(--sms-active-color, cornflowerblue));
+    height: var(--sms-selected-li-height);
   }
-  :where(ul.selected > li button, button.remove-all) {
+  :where(div.multiselect > ul.selected > li button, button.remove-all) {
     align-items: center;
     border-radius: 50%;
     display: flex;
     cursor: pointer;
     transition: 0.2s;
   }
-  :where(button) {
+  :where(div.multiselect button) {
     color: inherit;
     background: transparent;
     border: none;
@@ -329,36 +347,26 @@ display above those of another following shortly after it -->
     outline: none;
     padding: 0 2pt;
   }
-  :where(ul.selected > 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);
+  :where(div.multiselect > button:focus) {
     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);
+    color: var(--sms-text-color, inherit);
   }
 
-  :where(ul.selected) {
-    display: flex;
-    padding: 0;
-    margin: 0;
-    flex-wrap: wrap;
-    flex: 1;
-    overscroll-behavior: none;
-  }
-
-  :where(ul.options) {
+  :where(div.multiselect > ul.options) {
     list-style: none;
     max-height: 50vh;
     padding: 0;
@@ -368,15 +376,20 @@ display above those of another following shortly after it -->
     border-radius: 1ex;
     overflow: auto;
     background: var(--sms-options-bg, white);
+    overscroll-behavior: var(--sms-options-overscroll, none);
   }
-  :where(ul.options.hidden) {
+  :where(div.multiselect > ul.options.hidden) {
     visibility: hidden;
   }
-  :where(ul.options li) {
+  :where(div.multiselect > ul.options > li) {
     padding: 3pt 2ex;
     cursor: pointer;
   }
-  :where(ul.options li.selected) {
+  /* for noOptionsMsg */
+  :where(div.multiselect > ul.options span) {
+    padding: 3pt 2ex;
+  }
+  :where(div.multiselect > ul.options > li.selected) {
     border-left: var(
       --sms-li-selected-border-left,
       3pt solid var(--sms-selected-color, green)
@@ -384,22 +397,21 @@ display above those of another following shortly after it -->
     background: var(--sms-li-selected-bg, inherit);
     color: var(--sms-li-selected-color, inherit);
   }
-  :where(ul.options li:not(.selected):hover) {
+  :where(div.multiselect > ul.options > li:not(.selected):hover) {
     border-left: var(
       --sms-li-not-selected-hover-border-left,
       3pt solid var(--sms-active-color, cornflowerblue)
     );
-    border-left: 3pt solid var(--blue);
   }
-  :where(ul.options li.active) {
+  :where(div.multiselect > ul.options > li.active) {
     background: var(--sms-li-active-bg, var(--sms-active-color, cornflowerblue));
   }
-  :where(ul.options li.disabled) {
+  :where(div.multiselect > ul.options > li.disabled) {
+    cursor: not-allowed;
     background: var(--sms-li-disabled-bg, #f5f5f6);
     color: var(--sms-li-disabled-text, #b8b8b8);
-    cursor: not-allowed;
   }
-  :where(ul.options li.disabled:hover) {
+  :where(div.multiselect > ul.options > li.disabled:hover) {
     border-left: unset;
   }
 </style>

package/MultiSelect.svelte.d.ts

@@ -11,10 +11,11 @@ declare const __propDef: {
         options: ProtoOption[];
         input?: HTMLInputElement | null | undefined;
         placeholder?: string | undefined;
-        name?: string | undefined;
         id?: string | undefined;
+        name?: string | undefined;
         noOptionsMsg?: string | undefined;
         activeOption?: Option | null | undefined;
+        filterFunc?: ((op: Option, searchText: string) => boolean) | undefined;
         outerDivClass?: string | undefined;
         ulSelectedClass?: string | undefined;
         liSelectedClass?: string | undefined;
@@ -30,11 +31,11 @@ declare const __propDef: {
         [evt: string]: CustomEvent<any>;
     };
     slots: {
-        selectedRenderer: {
+        renderSelected: {
             option: Option;
             idx: any;
         };
-        optionRenderer: {
+        renderOptions: {
             option: Option;
             idx: any;
         };

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/actions.js

@@ -14,26 +14,3 @@ export function onClickOutside(node, cb) {
         },
     };
 }
-// import { spring } from 'svelte/motion'
-// export default function boop(node: HTMLElement, params = {}) {
-//   const { setter } = params
-//   const springyRotation = spring(
-//     { x: 0, y: 0, rotation: 0, scale: 1 },
-//     { stiffness: 0.1, damping: 0.15 }
-//   )
-//   node.style.display = `inline-block`
-//   const unsubscribe = springyRotation.subscribe(({ x, y, rotation, scale }) => {
-//     node.style.transform = `translate(${x}px, ${y}px) rotate(${rotation}deg) scale(${scale})`
-//   })
-//   return {
-//     update({ isBooped: x = 0, y = 0, rotation = 0, scale = 1, timing }) {
-//       springyRotation.set(
-//         isBooped
-//           ? { x, y, rotation, scale }
-//           : { x: 0, y: 0, rotation: 0, scale: 1 }
-//       )
-//       if (isBooped) window.setTimeout(() => setter(false), timing)
-//     },
-//     destroy: unsubscribe,
-//   }
-// }

package/package.json

@@ -5,32 +5,32 @@
   "homepage": "https://svelte-multiselect.netlify.app",
   "repository": "https://github.com/janosh/svelte-multiselect",
   "license": "MIT",
-  "version": "3.1.0",
+  "version": "3.2.2",
   "type": "module",
   "svelte": "index.js",
   "bugs": "https://github.com/janosh/svelte-multiselect/issues",
   "devDependencies": {
-    "@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",
+    "@sveltejs/adapter-static": "^1.0.0-next.28",
+    "@sveltejs/kit": "^1.0.0-next.269",
+    "@typescript-eslint/eslint-plugin": "^5.12.0",
+    "@typescript-eslint/parser": "^5.12.0",
+    "eslint": "^8.9.0",
     "eslint-plugin-svelte3": "^3.4.0",
     "hastscript": "^7.0.2",
-    "mdsvex": "^0.9.8",
+    "mdsvex": "^0.10.5",
     "prettier": "^2.5.1",
     "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": "^3.46.4",
+    "svelte-check": "^2.4.3",
     "svelte-github-corner": "^0.1.0",
-    "svelte-preprocess": "^4.10.2",
-    "svelte-toc": "^0.2.2",
-    "svelte2tsx": "^0.4.14",
+    "svelte-preprocess": "^4.10.3",
+    "svelte-toc": "^0.2.5",
+    "svelte2tsx": "^0.5.3",
     "tslib": "^2.3.1",
     "typescript": "^4.5.5",
-    "vite": "^2.7.13"
+    "vite": "^2.8.2"
   },
   "keywords": [
     "svelte",

package/readme.md

@@ -8,6 +8,7 @@
 [![Netlify Status](https://api.netlify.com/api/v1/badges/a45b62c3-ea45-4cfd-9912-77ec4fc8d7e8/deploy-status)](https://app.netlify.com/sites/svelte-multiselect/deploys)
 [![NPM version](https://img.shields.io/npm/v/svelte-multiselect?color=blue&logo=NPM)](https://npmjs.com/package/svelte-multiselect)
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/janosh/svelte-multiselect/main.svg)](https://results.pre-commit.ci/latest/github/janosh/svelte-multiselect/main)
+![Needs Svelte version](https://img.shields.io/npm/dependency-version/svelte-multiselect/dev/svelte)
 
 </h4>
 
@@ -21,12 +22,12 @@
 
 <slot />
 
-## Key Features
+## 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
@@ -34,7 +35,7 @@
 
 ## 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 as well, even if you still pass in `options` as strings.
+- 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
@@ -87,40 +88,59 @@ Full list of props/bindable variables for this component:
 <div class="table">
 
 <!-- prettier-ignore -->
-| name             | default                                                    | description                                                                                                                                                                                    |
-| :--------------- | :--------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `options`        | required prop                                              | Array of strings/numbers or `Option` objects that will be listed in the dropdown. See `src/lib/index.ts` for admissible fields. The `label` is the only mandatory one. It must also be unique. |
-| `activeOption`   | `null`                                                     | Currently active option, i.e. the one the user currently hovers or navigated to with arrow keys.                                                                                               |
-| `maxSelect`      | `null`                                                     | Positive integer to limit the number of options users can pick. `null` means no limit.                                                                                                         |
-| `maxSelectMsg`   | ``(current: number, max: number) => `${current}/${max}` `` | Function that returns a string informing the user how many of the maximum allowed options they have currently selected. Return empty string to disable, i.e. `() => ''`.                       |
-| `selected`       | `[]`                                                       | Array of currently/pre-selected options when binding/passing as props respectively.                                                                                                            |
-| `selectedLabels` | `[]`                                                       | Labels of currently selected options.                                                                                                                                                          |
-| `selectedValues` | `[]`                                                       | Values of currently selected options.                                                                                                                                                          |
-| `readonly`       | `false`                                                    | Disable the component. It will still be rendered but users won't be able to interact with it.                                                                                                  |
-| `placeholder`    | `undefined`                                                | String shown in the text input when no option is selected.                                                                                                                                     |
-| `input`          | `undefined`                                                | Handle to the `<input>` DOM node.                                                                                                                                                              |
-| `name`           | `undefined`                                                | Passed to the `<input>` for associating HTML form `<label>`s with this component. E.g. clicking a `<label>` with same name will focus this component.                                          |
-| `id`             | `undefined`                                                | Applied to the top-level `<div>` e.g. for `document.getElementById()`.                                                                                                                         |
+| name             | default       | description                                                                                                                                                                                                                                |
+| :--------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`        | required prop | Array of strings/numbers or `Option` objects that will be listed in the dropdown. See `src/lib/index.ts` for admissible fields. The `label` is the only mandatory one. It must also be unique.                                             |
+| `activeOption`   | `null`        | Currently active option, i.e. the one the user currently hovers or navigated to with arrow keys.                                                                                                                                           |
+| `maxSelect`      | `null`        | Positive integer to limit the number of options users can pick. `null` means no limit.                                                                                                                                                     |
+| `selected`       | `[]`          | Array of currently/pre-selected options when binding/passing as props respectively.                                                                                                                                                        |
+| `selectedLabels` | `[]`          | Labels of currently selected options.                                                                                                                                                                                                      |
+| `selectedValues` | `[]`          | Values of currently selected options.                                                                                                                                                                                                      |
+| `readonly`       | `false`       | Disable the component. It will still be rendered but users won't be able to interact with it.                                                                                                                                              |
+| `placeholder`    | `undefined`   | String shown in the text input when no option is selected.                                                                                                                                                                                 |
+| `input`          | `undefined`   | Handle to the `<input>` DOM node.                                                                                                                                                                                                          |
+| `id`             | `undefined`   | 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.                                       |
+| `name`           | `id`          | Applied to the `<input>` element. If not provided, will be set to the value of `id`. Sets the key of this field in a submitted form data object. Not useful at the moment since the value is stored in Svelte state, not on the `<input>`. |
 
 </div>
 
+## 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:
+
+   ```ts
+   filterFunc = (op: Option, searchText: string) => {
+     if (!searchText) return true
+     return `${op.label}`.toLowerCase().includes(searchText.toLowerCase())
+   }
+   ```
+
+2. `maxSelectMsg = (current: number, max: number) => string`: Inform the user how many of the maximum allowed options they have currently selected. Return empty string to disable, i.e. `() => ''`. Is automatically disabled when `maxSelect === null`. Defaults to:
+
+   ```ts
+   maxSelectMsg = (current: number, max: number) => `${current}/${max}`
+   ```
+
 ## Slots
 
 `MultiSelect.svelte` accepts two named slots
 
-- `slot="optionRenderer"`
-- `slot="selectedRenderer"`
+- `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`, `Watermelon`, `Apple`, `Dates`, `Mango`]}>
-  <span let:idx let:option slot="optionRenderer">
-    {idx + 1}. {option.label} {option.label === `Mango` ? `🎉` : ``}</span
-  >
-  <span let:idx let:option slot="selectedRenderer">
-    #️⃣ {idx + 1} {option.label}</span
-  >
+<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>
 ```
 
@@ -152,7 +172,7 @@ to customize rendering individual options in the dropdown and the list of select
 
 ## TypeScript
 
-TypeScript users can import the types used for internal type safety for external use as well:
+TypeScript users can import the types used for internal type safety:
 
 ```svelte
 <script lang="ts">
@@ -171,26 +191,57 @@ TypeScript users can import the types used for internal type safety for external
 
 ## 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-selected-bg, var(--sms-active-color, cornflowerblue))`: Background of selected options.
-- `color: var(--sms-remove-x-hover+focus-color, lightgray)`: Hover color of cross icon to remove selected options.
-- `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)`
+  - `background: var(--sms-input-bg)`
+  - `height: var(--sms-input-height, 2em)`
+- `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.readonly`
+  - `background: var(--sms-readonly-bg, lightgray)`: Background when in readonly state.
+- `div.multiselect > input`
+  - `color: var(--sms-text-color, inherit)`: Input text color.
+- `div.multiselect > ul.selected > li`
+  - `background: var(--sms-selected-bg, var(--sms-active-color, cornflowerblue))`: Background of selected options.
+  - `height: var(--sms-selected-li-height)`: Height of selected options.
+- `ul.selected > li button:hover, button.remove-all:hover, button:focus`
+  - `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.
+- `div.multiselect > ul.options`
+  - `background: var(--sms-options-bg, white)`: Background of dropdown list.
+  - `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](https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior).
+- `div.multiselect > ul.options > li.selected`
+  - `border-left: var(--sms-li-selected-border-left, 3pt solid var(--sms-selected-color, green))`
+  - `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.
+- `div.multiselect > ul.options > li:not(.selected):hover`
+  - `border-left: var(--sms-li-not-selected-hover-border-left, 3pt solid var(--sms-active-color, cornflowerblue))`
+- `div.multiselect > 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.
+- `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:
 
@@ -211,14 +262,14 @@ The second method allows you to pass in custom classes to the important DOM elem
 This simplified version of the DOM structure of this component shows where these classes are inserted:
 
 ```svelte
-<div class={outerDivClass}>
-  <ul class={ulSelectedClass}>
-    <li class={liSelectedClass}>First selected tag</li>
-    <li class={liSelectedClass}>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>
 ```
@@ -228,40 +279,47 @@ This simplified version of the DOM structure of this component shows where these
 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) {
+:global(div.multiselect) {
   /* top-level wrapper div */
 }
-:global(.multiselect ul.selected > li) {
-  /* selected options */
+:global(div.multiselect.open) {
+  /* top-level wrapper div when dropdown open */
+}
+:global(div.multiselect.readonly) {
+  /* top-level wrapper div when in readonly state */
+}
+:global(div.multiselect > ul.selected) {
+  /* selected list */
+}
+:global(div.multiselect > ul.selected > li) {
+  /* selected list items */
 }
-:global(.multiselect ul.selected > li button),
-:global(.multiselect button.remove-all) {
+: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(.multiselect ul.options) {
+:global(div.multiselect > input) {
+  /* input inside the top-level wrapper div */
+}
+:global(div.multiselect > ul.options) {
   /* dropdown options */
 }
-:global(.multiselect ul.options li) {
-  /* dropdown list of available options */
+:global(div.multiselect > ul.options > li) {
+  /* dropdown list items */
 }
-:global(.multiselect ul.options li.selected) {
+:global(div.multiselect > ul.options > li.selected) {
   /* selected options in the dropdown list */
 }
-:global(.multiselect ul.options li:not(.selected):hover) {
+:global(div.multiselect > ul.options > li:not(.selected):hover) {
   /* unselected but hovered options in the dropdown list */
 }
-:global(.multiselect ul.options li.selected:hover) {
-  /* selected and hovered options in the dropdown list */
-  /* probably not necessary to style this state in most cases */
-}
-:global(.multiselect ul.options li.active) {
+: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(.multiselect ul.options li.selected.active) {
-  /* both active and already selected, pressing enter now will deselect the item */
-}
-:global(.multiselect ul.options li.disabled) {
+:global(div.multiselect > ul.options > li.disabled) {
   /* options with disabled key set to true (see props above) */
 }
 ```