svelte-multiselect 8.6.2 → 10.0.0

package/dist/CmdPalette.svelte

@@ -1,27 +1,25 @@
-<script>/* eslint-disable no-undef */ // TODO: remove when fixed
-// https://github.com/sveltejs/eslint-plugin-svelte3/issues/201
-import { tick } from 'svelte';
+<script>import { tick } from 'svelte';
 import { fade } from 'svelte/transition';
-import Select from '.';
+import Select from './MultiSelect.svelte';
 export let actions;
-export let trigger = `k`;
+export let triggers = [`k`];
+export let close_keys = [`Escape`];
 export let fade_duration = 200; // in ms
 export let style = ``; // for dialog
-// for span in option slot, has no effect when passing slot="option"
+// for span in option slot, has no effect when passing a slot
 export let span_style = ``;
 export let open = false;
 export let dialog = null;
 export let input = null;
 export let placeholder = `Filter actions...`;
 async function toggle(event) {
-    if (event.key === trigger && event.metaKey && !open) {
+    if (triggers.includes(event.key) && event.metaKey && !open) {
         // open on cmd+trigger
         open = true;
         await tick(); // wait for dialog to open and input to be mounted
         input?.focus();
     }
-    else if (event.key === `Escape` && open) {
-        // close on escape
+    else if (close_keys.includes(event.key) && open) {
         open = false;
     }
 }
@@ -39,22 +37,18 @@ function run_and_close(event) {
 <svelte:window on:keydown={toggle} on:click={close_if_outside} />
 
 {#if open}
-  <dialog
-    class:open
-    bind:this={dialog}
-    transition:fade={{ duration: fade_duration }}
-    {style}
-  >
+  <dialog open bind:this={dialog} transition:fade={{ duration: fade_duration }} {style}>
     <Select
       options={actions}
       bind:input
       {placeholder}
       on:add={run_and_close}
       on:keydown={toggle}
-      {...$$props}
+      {...$$restProps}
+      let:option
     >
       <!-- wait for https://github.com/sveltejs/svelte/pull/8304 -->
-      <slot slot="option" name="option" let:option>
+      <slot>
         <span style={span_style}>{option.label}</span>
       </slot>
     </Select>

package/dist/CmdPalette.svelte.d.ts

@@ -6,7 +6,8 @@ declare const __propDef: {
             label: string;
             action: () => void;
         }[];
-        trigger?: string | undefined;
+        triggers?: string[] | undefined;
+        close_keys?: string[] | undefined;
         fade_duration?: number | undefined;
         style?: string | undefined;
         span_style?: string | undefined;
@@ -19,9 +20,7 @@ declare const __propDef: {
         [evt: string]: CustomEvent<any>;
     };
     slots: {
-        option: {
-            slot: string;
-        };
+        default: {};
     };
 };
 export type CmdPaletteProps = typeof __propDef.props;

package/dist/MultiSelect.svelte

@@ -14,15 +14,16 @@ export let breakpoint = 800; // any screen with more horizontal pixels is consid
 export let defaultDisabledTitle = `This option is disabled`;
 export let disabled = false;
 export let disabledInputTitle = `This input is disabled`;
-// case-insensitive equality comparison after string coercion (looking only at the `label` key of object options)
 // prettier-ignore
-export let duplicateFunc = (op1, op2) => `${get_label(op1)}`.toLowerCase() === `${get_label(op2)}`.toLowerCase();
 export let duplicateOptionMsg = `This option is already selected`;
 export let duplicates = false; // whether to allow duplicate options
-export let filterFunc = (op, searchText) => {
+// takes two options and returns true if they are equal
+// case-insensitive equality comparison after string coercion and looks only at the `label` key of object options by default
+export let key = (opt) => `${get_label(opt)}`.toLowerCase();
+export let filterFunc = (opt, searchText) => {
     if (!searchText)
         return true;
-    return `${get_label(op)}`.toLowerCase().includes(searchText.toLowerCase());
+    return `${get_label(opt)}`.toLowerCase().includes(searchText.toLowerCase());
 };
 export let focusInputOnSelect = `desktop`;
 export let form_input = null;
@@ -37,6 +38,7 @@ export let liOptionClass = ``;
 export let liSelectedClass = ``;
 export let loading = false;
 export let matchingOptions = [];
+export let maxOptions = undefined;
 export let maxSelect = null; // null means there is no upper limit for selected.length
 export let maxSelectMsg = (current, max) => (max > 1 ? `${current}/${max}` : ``);
 export let maxSelectMsgClass = ``;
@@ -56,7 +58,7 @@ export let required = false;
 export let resetFilterOnAdd = true;
 export let searchText = ``;
 export let selected = options
-    ?.filter((op) => op instanceof Object && op?.preselected)
+    ?.filter((opt) => opt instanceof Object && opt?.preselected)
     .slice(0, maxSelect ?? undefined) ?? [];
 export let sortSelected = false;
 export let selectedOptionsDraggable = !sortSelected;
@@ -64,14 +66,14 @@ export let ulOptionsClass = ``;
 export let ulSelectedClass = ``;
 export let value = null;
 // get the label key from an option object or the option itself if it's a string or number
-export const get_label = (op) => {
-    if (op instanceof Object) {
-        if (op.label === undefined) {
-            console.error(`MultiSelect option ${JSON.stringify(op)} is an object but has no label key`);
+export const get_label = (opt) => {
+    if (opt instanceof Object) {
+        if (opt.label === undefined) {
+            console.error(`MultiSelect option ${JSON.stringify(opt)} is an object but has no label key`);
         }
-        return op.label;
+        return opt.label;
     }
-    return op;
+    return `${opt}`;
 };
 // if maxSelect=1, value is the single item in selected (or null if selected is empty)
 // this solves both https://github.com/janosh/svelte-multiselect/issues/86 and
@@ -108,12 +110,17 @@ if (allowUserOptions && !createOptionMsg && createOptionMsg !== null) {
     console.error(`MultiSelect has allowUserOptions=${allowUserOptions} but createOptionMsg=${createOptionMsg} is falsy. ` +
         `This prevents the "Add option" <span> from showing up, resulting in a confusing user experience.`);
 }
+if (maxOptions &&
+    (typeof maxOptions != `number` || maxOptions < 0 || maxOptions % 1 != 0)) {
+    console.error(`MultiSelect's maxOptions must be undefined or a positive integer, got ${maxOptions}`);
+}
 const dispatch = createEventDispatcher();
 let option_msg_is_active = false; // controls active state of <li>{createOptionMsg}</li>
 let window_width;
 // options matching the current search text
-$: matchingOptions = options.filter((op) => filterFunc(op, searchText) && !selected.includes(op) // remove already selected options from dropdown list
-);
+$: matchingOptions = options.filter((opt) => filterFunc(opt, searchText) &&
+    // remove already selected options from dropdown list unless duplicate selections are allowed
+    (!selected.map(key).includes(key(opt)) || duplicates));
 // raise if matchingOptions[activeIndex] does not yield a value
 if (activeIndex !== null && !matchingOptions[activeIndex]) {
     throw `Run time error, activeIndex=${activeIndex} is out of bounds, matchingOptions.length=${matchingOptions.length}`;
@@ -127,7 +134,7 @@ function add(option, event) {
     if (!isNaN(Number(option)) && typeof selected.map(get_label)[0] === `number`) {
         option = Number(option); // convert to number if possible
     }
-    const is_duplicate = selected.some((op) => duplicateFunc(op, option));
+    const is_duplicate = selected.map(key).includes(key(option));
     if ((maxSelect === null || maxSelect === 1 || selected.length < maxSelect) &&
         (duplicates || !is_duplicate)) {
         if (!options.includes(option) && // first check if we find option in the options list
@@ -194,7 +201,7 @@ function add(option, event) {
 function remove(to_remove) {
     if (selected.length === 0)
         return;
-    const idx = selected.findIndex((op) => JSON.stringify(op) === JSON.stringify(to_remove));
+    const idx = selected.findIndex((opt) => key(opt) === key(to_remove));
     let [option] = selected.splice(idx, 1); // remove option from selected list
     if (option === undefined && allowUserOptions) {
         // if option with label could not be found but allowUserOptions is truthy,
@@ -339,6 +346,7 @@ const dragstart = (idx) => (event) => {
     event.dataTransfer.setData(`text/plain`, `${idx}`);
 };
 let ul_options;
+// highlight text matching user-entered search text in available options
 function highlight_matching_options(event) {
     if (!highlightMatches || typeof CSS == `undefined` || !CSS.highlights)
         return; // don't try if CSS highlight API not supported
@@ -404,7 +412,10 @@ function highlight_matching_options(event) {
   on:mouseup|stopPropagation={open_dropdown}
   title={disabled ? disabledInputTitle : null}
   data-id={id}
+  role="searchbox"
+  tabindex="-1"
 >
+  <!-- form control input invisible to the user, only purpose is to abort form submission if this component fails data validation -->
   <!-- bind:value={selected} prevents form submission if required prop is true and no options are selected -->
   <input
     {name}
@@ -432,9 +443,11 @@ function highlight_matching_options(event) {
     <ExpandIcon width="15px" style="min-width: 1em; padding: 0 1pt; cursor: pointer;" />
   </slot>
   <ul class="selected {ulSelectedClass}" aria-label="selected options">
-    {#each selected as option, idx (option)}
+    {#each selected as option, idx (duplicates ? [key(option), idx] : key(option))}
       <li
         class={liSelectedClass}
+        role="option"
+        aria-selected="true"
         animate:flip={{ duration: 100 }}
         draggable={selectedOptionsDraggable && !disabled && selected.length > 1}
         on:dragstart={dragstart(idx)}
@@ -445,10 +458,13 @@ function highlight_matching_options(event) {
       >
         <!-- on:dragover|preventDefault needed for the drop to succeed https://stackoverflow.com/a/31085796 -->
         <slot name="selected" {option} {idx}>
-          {#if parseLabelsAsHtml}
-            {@html get_label(option)}
-          {:else}
-            {get_label(option)}{/if}
+          <slot {option} {idx}>
+            {#if parseLabelsAsHtml}
+              {@html get_label(option)}
+            {:else}
+              {get_label(option)}
+            {/if}
+          </slot>
         </slot>
         {#if !disabled && (minSelect === null || selected.length > minSelect)}
           <button
@@ -496,6 +512,16 @@ function highlight_matching_options(event) {
       on:touchstart
     />
     <!-- the above on:* lines forward potentially useful DOM events -->
+    <slot
+      name="after-input"
+      {selected}
+      {disabled}
+      {invalid}
+      {id}
+      {placeholder}
+      {open}
+      {required}
+    />
   </ul>
   {#if loading}
     <slot name="spinner">
@@ -529,10 +555,18 @@ function highlight_matching_options(event) {
     {/if}
   {/if}
 
-  <!-- only render options dropdown if options or searchText is not empty needed to avoid briefly flashing empty dropdown -->
+  <!-- only render options dropdown if options or searchText is not empty (needed to avoid briefly flashing empty dropdown) -->
   {#if (searchText && noMatchingOptionsMsg) || options?.length > 0}
-    <ul class:hidden={!open} class="options {ulOptionsClass}" bind:this={ul_options}>
-      {#each matchingOptions as option, idx}
+    <ul
+      class:hidden={!open}
+      class="options {ulOptionsClass}"
+      role="listbox"
+      aria-multiselectable={maxSelect === null || maxSelect > 1}
+      aria-expanded={open}
+      aria-disabled={disabled ? `true` : null}
+      bind:this={ul_options}
+    >
+      {#each matchingOptions.slice(0, Math.max(0, maxOptions ?? 0) || Infinity) as option, idx}
         {@const {
           label,
           disabled = null,
@@ -561,21 +595,25 @@ function highlight_matching_options(event) {
           }}
           on:mouseout={() => (activeIndex = null)}
           on:blur={() => (activeIndex = null)}
+          role="option"
+          aria-selected="false"
         >
           <slot name="option" {option} {idx}>
-            {#if parseLabelsAsHtml}
-              {@html get_label(option)}
-            {:else}
-              {get_label(option)}
-            {/if}
+            <slot {option} {idx}>
+              {#if parseLabelsAsHtml}
+                {@html get_label(option)}
+              {:else}
+                {get_label(option)}
+              {/if}
+            </slot>
           </slot>
         </li>
       {:else}
-        {@const search_is_duplicate = selected.some((option) =>
-          duplicateFunc(option, searchText)
-        )}
+        {@const textInputIsDuplicate = selected.map(get_label).includes(searchText)}
+        <!-- set msg to duplicateOptionMsg if duplicates are not allowed and the user-entered
+          searchText is a duplicate, else set to createOptionMsg -->
         {@const msg =
-          !duplicates && search_is_duplicate ? duplicateOptionMsg : createOptionMsg}
+          !duplicates && textInputIsDuplicate ? duplicateOptionMsg : createOptionMsg}
         {#if allowUserOptions && searchText && msg}
           <li
             on:mousedown|stopPropagation
@@ -586,9 +624,20 @@ function highlight_matching_options(event) {
             on:focus={() => (option_msg_is_active = true)}
             on:mouseout={() => (option_msg_is_active = false)}
             on:blur={() => (option_msg_is_active = false)}
+            role="option"
+            aria-selected="false"
             class="user-msg"
           >
-            {msg}
+            <slot
+              name="user-msg"
+              {duplicateOptionMsg}
+              {createOptionMsg}
+              {textInputIsDuplicate}
+              {searchText}
+              {msg}
+            >
+              {msg}
+            </slot>
           </li>
         {:else if noMatchingOptionsMsg}
           <!-- use span to not have cursor: pointer -->

package/dist/MultiSelect.svelte.d.ts

@@ -13,10 +13,10 @@ declare class __sveltets_Render<Option extends T> {
         defaultDisabledTitle?: string | undefined;
         disabled?: boolean | undefined;
         disabledInputTitle?: string | undefined;
-        duplicateFunc?: ((op1: T, op2: T) => boolean) | undefined;
         duplicateOptionMsg?: string | undefined;
         duplicates?: boolean | undefined;
-        filterFunc?: ((op: Option, searchText: string) => boolean) | undefined;
+        key?: ((opt: T) => unknown) | undefined;
+        filterFunc?: ((opt: Option, searchText: string) => boolean) | undefined;
         focusInputOnSelect?: boolean | "desktop" | undefined;
         form_input?: HTMLInputElement | null | undefined;
         highlightMatches?: boolean | undefined;
@@ -30,6 +30,7 @@ declare class __sveltets_Render<Option extends T> {
         liSelectedClass?: string | undefined;
         loading?: boolean | undefined;
         matchingOptions?: Option[] | undefined;
+        maxOptions?: number | undefined;
         maxSelect?: number | null | undefined;
         maxSelectMsg?: ((current: number, max: number) => string) | null | undefined;
         maxSelectMsgClass?: string | undefined;
@@ -54,7 +55,7 @@ declare class __sveltets_Render<Option extends T> {
         ulOptionsClass?: string | undefined;
         ulSelectedClass?: string | undefined;
         value?: Option | Option[] | null | undefined;
-        get_label?: ((op: T) => string | number) | undefined;
+        get_label?: ((opt: T) => string | number) | undefined;
     };
     events(): MultiSelectEvents;
     slots(): {
@@ -65,19 +66,39 @@ declare class __sveltets_Render<Option extends T> {
             option: Option;
             idx: any;
         };
+        default: {
+            option: Option;
+            idx: any;
+        };
         'remove-icon': {};
+        'after-input': {
+            selected: Option[];
+            disabled: boolean;
+            invalid: boolean;
+            id: string | null;
+            placeholder: string | null;
+            open: boolean;
+            required: number | boolean;
+        };
         spinner: {};
         'disabled-icon': {};
         option: {
             option: Option;
             idx: any;
         };
+        'user-msg': {
+            duplicateOptionMsg: string;
+            createOptionMsg: string | null;
+            textInputIsDuplicate: any;
+            searchText: string;
+            msg: any;
+        };
     };
 }
 export type MultiSelectProps<Option extends T> = ReturnType<__sveltets_Render<Option>['props']>;
 export type MultiSelectEvents<Option extends T> = ReturnType<__sveltets_Render<Option>['events']>;
 export type MultiSelectSlots<Option extends T> = ReturnType<__sveltets_Render<Option>['slots']>;
 export default class MultiSelect<Option extends T> extends SvelteComponentTyped<MultiSelectProps<Option>, MultiSelectEvents<Option>, MultiSelectSlots<Option>> {
-    get get_label(): (op: T) => string | number;
+    get get_label(): (opt: T) => string | number;
 }
 export {};

package/package.json

@@ -5,7 +5,7 @@
   "homepage": "https://janosh.github.io/svelte-multiselect",
   "repository": "https://github.com/janosh/svelte-multiselect",
   "license": "MIT",
-  "version": "8.6.2",
+  "version": "10.0.0",
   "type": "module",
   "svelte": "./dist/index.js",
   "bugs": "https://github.com/janosh/svelte-multiselect/issues",
@@ -19,41 +19,41 @@
     "test": "vitest --run --coverage tests/unit/*.ts && playwright test tests/*.test.ts",
     "test:unit": "vitest tests/unit/*.ts",
     "test:e2e": "playwright test tests/*.test.ts",
-    "changelog": "npx auto-changelog --package --output changelog.md --unreleased-only --hide-credit --commit-limit false",
+    "changelog": "npx auto-changelog --package --output changelog.md --hide-empty-releases --hide-credit --commit-limit false",
     "update-coverage": "vitest tests/unit --run --coverage && npx istanbul-badges-readme"
   },
   "dependencies": {
-    "svelte": "^3.59.1"
+    "svelte": "^4.0.1"
   },
   "devDependencies": {
-    "@iconify/svelte": "^3.1.3",
-    "@playwright/test": "^1.33.0",
+    "@iconify/svelte": "^3.1.4",
+    "@playwright/test": "^1.35.1",
     "@sveltejs/adapter-static": "^2.0.2",
-    "@sveltejs/kit": "^1.16.3",
-    "@sveltejs/package": "2.0.2",
-    "@sveltejs/vite-plugin-svelte": "^2.2.0",
-    "@typescript-eslint/eslint-plugin": "^5.59.5",
-    "@typescript-eslint/parser": "^5.59.5",
-    "@vitest/coverage-c8": "^0.31.0",
-    "eslint": "^8.40.0",
-    "eslint-plugin-svelte3": "^4.0.0",
+    "@sveltejs/kit": "^1.21.0",
+    "@sveltejs/package": "2.1.0",
+    "@sveltejs/vite-plugin-svelte": "2.4.2",
+    "@typescript-eslint/eslint-plugin": "^5.60.1",
+    "@typescript-eslint/parser": "^5.60.1",
+    "@vitest/coverage-v8": "^0.32.2",
+    "eslint": "^8.44.0",
+    "eslint-plugin-svelte": "^2.32.2",
     "hastscript": "^7.2.0",
     "highlight.js": "^11.8.0",
-    "jsdom": "^22.0.0",
-    "mdsvex": "^0.10.6",
+    "jsdom": "^22.1.0",
+    "mdsvex": "^0.11.0",
     "mdsvexamples": "^0.3.3",
     "prettier": "^2.8.8",
-    "prettier-plugin-svelte": "^2.10.0",
+    "prettier-plugin-svelte": "^2.10.1",
     "rehype-autolink-headings": "^6.1.1",
     "rehype-slug": "^5.1.0",
-    "svelte-check": "^3.3.2",
-    "svelte-preprocess": "^5.0.3",
+    "svelte-check": "^3.4.4",
+    "svelte-preprocess": "^5.0.4",
     "svelte-toc": "^0.5.5",
-    "svelte-zoo": "^0.4.5",
-    "svelte2tsx": "^0.6.14",
-    "typescript": "5.0.4",
-    "vite": "^4.3.6",
-    "vitest": "^0.31.0"
+    "svelte-zoo": "^0.4.8",
+    "svelte2tsx": "^0.6.16",
+    "typescript": "5.1.6",
+    "vite": "^4.3.9",
+    "vitest": "^0.32.2"
   },
   "keywords": [
     "svelte",
@@ -77,6 +77,7 @@
       "default": "./dist/index.js"
     }
   },
+  "types": "./dist/index.d.ts",
   "files": [
     "dist"
   ]

package/readme.md

@@ -8,7 +8,7 @@
 [![Tests](https://github.com/janosh/svelte-multiselect/actions/workflows/test.yml/badge.svg)](https://github.com/janosh/svelte-multiselect/actions/workflows/test.yml)
 [![GitHub Pages](https://github.com/janosh/svelte-multiselect/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/janosh/svelte-multiselect/actions/workflows/gh-pages.yml)
 [![NPM version](https://img.shields.io/npm/v/svelte-multiselect?logo=NPM&color=purple)](https://npmjs.com/package/svelte-multiselect)
-[![Needs Svelte version](https://img.shields.io/npm/dependency-version/svelte-multiselect/svelte?color=teal&logo=Svelte&label=Svelte)](https://github.com/sveltejs/svelte/blob/master/CHANGELOG.md)
+[![Needs Svelte version](https://img.shields.io/npm/dependency-version/svelte-multiselect/svelte?color=teal&logo=Svelte&label=Svelte)](https://github.com/sveltejs/svelte/blob/master/packages/svelte/CHANGELOG.md)
 [![REPL](https://img.shields.io/badge/Svelte-REPL-blue?label=Try%20it!)](https://svelte.dev/repl/a5a14b8f15d64cb083b567292480db05)
 [![Open in StackBlitz](https://img.shields.io/badge/Open%20in-StackBlitz-darkblue?logo=stackblitz)](https://stackblitz.com/github/janosh/svelte-multiselect)
 
@@ -36,16 +36,37 @@
 
 ## 🧪   Coverage
 
-| Statements                                                                                 | Branches                                                                             | Lines                                                                            |
-| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
-| ![Statements](https://img.shields.io/badge/statements-92.95%25-brightgreen.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-100%25-brightgreen.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-92.95%25-brightgreen.svg?style=flat) |
+| Statements                                                                                 | Branches                                                                       | Lines                                                                            |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| ![Statements](https://img.shields.io/badge/statements-97.94%25-brightgreen.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-79.39%25-red.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-97.94%25-brightgreen.svg?style=flat) |
 
 ## 📜   Breaking changes
 
-- **8.0.0** 
+- **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](https://github.com/janosh/svelte-multiselect/pull/138)
   - Prop `noOptionsMsg` was renamed to `noMatchingOptionsMsg`. [PR 133](https://github.com/janosh/svelte-multiselect/pull/133).
-- **v8.3.0**  `addOptionMsg` was renamed to `createOptionMsg` (no major since version since it's rarely used) [sha](https://github.com/janosh/svelte-multiselect/commits).
+- **v8.3.0** (2023-01-25)  `addOptionMsg` was renamed to `createOptionMsg` (no major since version since it's rarely used) [sha](https://github.com/janosh/svelte-multiselect/commits).
+- **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:
+
+  ```diff
+  <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)&nbsp; `duplicateFunc()` renamed to `key` in [#238](https://github.com/janosh/svelte-multiselect/pull/238). Signature changed:
+
+  ```diff
+  - 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](https://github.com/janosh/svelte-multiselect/pull/217)).
 
 ## 🔨 &thinsp; Installation
 
@@ -144,30 +165,29 @@ Full list of props/bindable variables for this component. The `Option` type you
 
    Tooltip text to display on hover when the component is in `disabled` state.
 
-<!-- prettier-ignore -->
 1. ```ts
-   duplicateFunc: (op1: T, op2: T) => boolean = (op1, op2) =>
-    `${get_label(op1)}`.toLowerCase() === `${get_label(op2)}`.toLowerCase()
+   duplicates: boolean = false
    ```
 
-   This option determines when two options are considered duplicates. Defaults to case-insensitive equality comparison after string coercion (looking only at the `label` key of object options). I.e. the default `duplicateFunc` considers `'Foo' == 'foo'`, `'42' == 42` and ``{ label: `Foo`, value: 0 } == { label: `foo`, value: 42 }``.
+   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.
 
 1. ```ts
-   duplicates: boolean = false
+   duplicateOptionMsg: string = `This option is already selected`
    ```
 
-   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 `duplicateFunc` to customize when a pair of options is considered a duplicate.
+   Text to display to users when `allowUserOptions` is truthy and they try to create a new option that's already selected.
 
+<!-- prettier-ignore -->
 1. ```ts
-   duplicateOptionMsg: string = `This option is already selected`
+   key: (opt: T) => unknown = (opt) => `${get_label(opt)}`.toLowerCase()
    ```
 
-   Text to display to users when `allowUserOptions` is truthy and they try to create a new option that's already selected.
+   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}`.
 
 1. ```ts
-   filterFunc = (op: Option, searchText: string): boolean => {
+   filterFunc = (opt: Option, searchText: string): boolean => {
      if (!searchText) return true
-     return `${get_label(op)}`.toLowerCase().includes(searchText.toLowerCase())
+     return `${get_label(opt)}`.toLowerCase().includes(searchText.toLowerCase())
    }
    ```
 
@@ -189,7 +209,7 @@ Full list of props/bindable variables for this component. The `Option` type you
    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](https://developer.mozilla.org/docs/Web/API/CSS_Custom_Highlight_API) with limited browser support and [styling options](https://developer.mozilla.org/docs/Web/CSS/::highlight). See `::highlight(sms-search-matches)` below for available CSS variables.
+   Whether to highlight text in the dropdown options that matches the current user-entered search query. Uses the [CSS Custom Highlight API](https://developer.mozilla.org/docs/Web/API/CSS_Custom_Highlight_API) with [limited browser support](https://caniuse.com/mdn-api_css_highlights) (70% as of May 2023) and [styling options](https://developer.mozilla.org/docs/Web/CSS/::highlight). See `::highlight(sms-search-matches)` below for available CSS variables.
 
 1. ```ts
    id: string | null = null
@@ -207,7 +227,7 @@ Full list of props/bindable variables for this component. The `Option` type you
    inputmode: string | null = null
    ```
 
-   The `inputmode` attribute hints at the type of data the user may enter. Values like `'numeric' | 'tel' | 'email'` allow browsers to display an appropriate virtual keyboard. See [MDN](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/inputmode) for details.
+   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](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/inputmode) 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"`.
 
 1. ```ts
    invalid: boolean = false
@@ -227,6 +247,12 @@ Full list of props/bindable variables for this component. The `Option` type you
 
    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`.
 
+1. ```ts
+   maxOptions: number | undefined = undefined
+   ```
+
+   Positive integer to limit the number of options displayed in the dropdown. `undefined` and 0 mean no limit.
+
 1. ```ts
    maxSelect: number | null = null
    ```
@@ -371,18 +397,20 @@ Full list of props/bindable variables for this component. The `Option` type you
 1. `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.
 1. `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.
 1. `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.
+1. `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). `let:props`:
+   - `duplicateOptionMsg: string`: See [props](#🔣-props).
+   - `createOptionMsg: string`: See [props](#🔣-props).
+   - `textInputIsDuplicate: boolean`: Whether user has typed text that matches an already existing option.
+   - `searchText: string`: The text user typed into search input.
+   - `msg: string`: `duplicateOptionMsg` if user input is a duplicate else `createOptionMsg`.
+1. `slot='after-input'`: ForPlaced after the search input. For arbitrary content like icons or temporary messages. Receives props `selected`, `disabled`, `invalid`, `id`, `placeholder`, `open`, `required`.
 
-Example:
+Example using several slots:
 
 ```svelte
-<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">
+<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;" />