svelte-multiselect 1.2.3 → 2.0.0

package/MultiSelect.svelte

@@ -1,17 +1,20 @@
-<script >import { createEventDispatcher } from 'svelte';
+<script >import { createEventDispatcher, onMount } from 'svelte';
 import { fly } from 'svelte/transition';
-import CrossIcon from './icons/Cross.svelte';
-import ExpandIcon from './icons/ChevronExpand.svelte';
-import ReadOnlyIcon from './icons/ReadOnly.svelte';
-export let selected;
+import { onClickOutside } from './actions';
+import { CrossIcon, ExpandIcon, ReadOnlyIcon } from './icons';
+export let selected = [];
+export let selectedLabels = [];
+export let selectedValues = [];
 export let maxSelect = null; // null means any number of options are selectable
+export let maxSelectMsg = (current, max) => `${current}/${max}`;
 export let readonly = false;
-export let placeholder = ``;
 export let options;
-export let disabledOptions = [];
 export let input = null;
-export let name = ``;
+export let placeholder = undefined;
+export let name = undefined;
+export let id = undefined;
 export let noOptionsMsg = `No matching options`;
+export let activeOption = null;
 export let outerDivClass = ``;
 export let ulTokensClass = ``;
 export let liTokenClass = ``;
@@ -19,47 +22,89 @@ export let ulOptionsClass = ``;
 export let liOptionClass = ``;
 export let removeBtnTitle = `Remove`;
 export let removeAllTitle = `Remove all`;
+export let defaultDisabledTitle = `This option is disabled`;
 if (maxSelect !== null && maxSelect < 0) {
-    throw new TypeError(`maxSelect must be null or positive integer, got ${maxSelect}`);
+    console.error(`maxSelect must be null or positive integer, got ${maxSelect}`);
 }
-$: single = maxSelect === 1;
-if (!selected)
-    selected = single ? `` : [];
 if (!(options?.length > 0))
     console.error(`MultiSelect missing options`);
-$: invalidDisabledOptions = disabledOptions.filter((opt) => !options.includes(opt));
-$: if (invalidDisabledOptions.length > 0) {
-    console.error(`Some disabledOptions are invalid as they do not appear in the options list: ${invalidDisabledOptions}`);
+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);
+});
+// 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
+    if (isObject(rawOp)) {
+        const op = { ...rawOp };
+        if (!op.value)
+            op.value = op.label;
+        return op;
+    }
+    else {
+        if (![`string`, `number`].includes(typeof rawOp)) {
+            console.error(`MultiSelect options must be objects, strings or numbers, got ${typeof rawOp}`);
+        }
+        // even if we logged error above, try to proceed hoping user knows what they're doing
+        return { label: rawOp, value: rawOp };
+    }
+});
+$: labels = _options.map((op) => op.label);
+$: if (new Set(labels).size !== options.length) {
+    console.error(`Option labels must be unique. Duplicates found: ${labels.filter((label, idx) => labels.indexOf(label) !== idx)}`);
+}
+$: selectedLabels = selected.map((op) => op.label);
+$: selectedValues = selected.map((op) => op.value);
 const dispatch = createEventDispatcher();
-let activeOption, searchText;
+let searchText = ``;
 let showOptions = false;
-$: filteredOptions = searchText
-    ? options.filter((option) => option.toLowerCase().includes(searchText.toLowerCase()))
-    : options;
-$: if ((activeOption && !filteredOptions.includes(activeOption)) ||
+// options matching the current search text
+$: matchingOptions = _options.filter((op) => {
+    if (!searchText)
+        return true;
+    return `${op.label}`.toLowerCase().includes(searchText.toLowerCase());
+});
+$: matchingEnabledOptions = matchingOptions.filter((op) => !op.disabled);
+$: if (
+// if there was an active option but it's not in the filtered list of options
+(activeOption &&
+    !matchingEnabledOptions.map((op) => op.label).includes(activeOption.label)) ||
+    // or there's no active option but the user entered search text
     (!activeOption && searchText))
-    activeOption = filteredOptions[0];
-function add(token) {
+    // make the first filtered option active
+    activeOption = matchingEnabledOptions[0];
+function add(label) {
     if (!readonly &&
-        !selected.includes(token) &&
-        // (... || single) because in single mode, we always replace current token with new selection
-        (maxSelect === null || selected.length < maxSelect || single)) {
+        !selectedLabels.includes(label) &&
+        // for maxselect = 1 we always replace current token with new selection
+        (maxSelect == null || maxSelect == 1 || selected.length < maxSelect)) {
         searchText = ``; // reset search string on selection
-        selected = single ? token : [token, ...selected];
-        if ((Array.isArray(selected) && selected.length === maxSelect) ||
-            typeof selected === `string`) {
-            setOptionsVisible(false);
-            input?.blur();
+        const token = _options.find((op) => op.label === label);
+        if (!token) {
+            console.error(`MultiSelect: option with label ${label} not found`);
+            return;
         }
+        if (maxSelect === 1) {
+            selected = [token];
+        }
+        else {
+            selected = [token, ...selected];
+        }
+        if (selected.length === maxSelect)
+            setOptionsVisible(false);
         dispatch(`add`, { token });
         dispatch(`change`, { token, type: `add` });
     }
 }
-function remove(token) {
-    if (readonly || typeof selected === `string`)
+function remove(label) {
+    if (selected.length === 0 || readonly)
         return;
-    selected = selected.filter((item) => item !== token);
+    selected = selected.filter((token) => label !== token.label);
+    const token = _options.find((option) => option.label === label);
     dispatch(`remove`, { token });
     dispatch(`change`, { token, type: `remove` });
 }
@@ -70,57 +115,64 @@ function setOptionsVisible(show) {
     showOptions = show;
     if (show)
         input?.focus();
+    else {
+        input?.blur();
+        activeOption = null;
+    }
 }
+// handle all keyboard events this component receives
 function handleKeydown(event) {
+    // on escape: dismiss options dropdown and reset search text
     if (event.key === `Escape`) {
         setOptionsVisible(false);
         searchText = ``;
     }
+    // on enter key: toggle active option and reset search text
     else if (event.key === `Enter`) {
         if (activeOption) {
-            if (isDisabled(activeOption))
+            const { label, disabled } = activeOption;
+            if (disabled)
                 return;
-            selected.includes(activeOption) ? remove(activeOption) : add(activeOption);
+            selectedLabels.includes(label) ? remove(label) : add(label);
             searchText = ``;
-        } // no active option means the options are closed in which case enter means open
+        } // no active option means the options dropdown is closed in which case enter means open it
         else
             setOptionsVisible(true);
     }
+    // on up/down arrow keys: update active option
     else if ([`ArrowDown`, `ArrowUp`].includes(event.key)) {
+        if (activeOption === null) {
+            // if no option is active yet, make first one active
+            activeOption = matchingEnabledOptions[0];
+            return;
+        }
         const increment = event.key === `ArrowUp` ? -1 : 1;
-        const newActiveIdx = filteredOptions.indexOf(activeOption) + increment;
+        const newActiveIdx = matchingEnabledOptions.indexOf(activeOption) + increment;
         if (newActiveIdx < 0) {
-            activeOption = filteredOptions[filteredOptions.length - 1];
+            // wrap around top
+            activeOption = matchingEnabledOptions[matchingEnabledOptions.length - 1];
+            // wrap around bottom
         }
-        else {
-            if (newActiveIdx === filteredOptions.length)
-                activeOption = filteredOptions[0];
-            else
-                activeOption = filteredOptions[newActiveIdx];
+        else if (newActiveIdx === matchingEnabledOptions.length) {
+            activeOption = matchingEnabledOptions[0];
+            // default case
         }
+        else
+            activeOption = matchingEnabledOptions[newActiveIdx];
     }
     else if (event.key === `Backspace`) {
-        // only remove selected tags on backspace if if there are any and no searchText characters remain
-        if (selected.length > 0 && searchText.length === 0) {
-            selected = selected.slice(0, selected.length - 1);
-        }
+        const label = selectedLabels.pop();
+        if (label && !searchText)
+            remove(label);
     }
 }
 const removeAll = () => {
     dispatch(`remove`, { token: selected });
     dispatch(`change`, { token: selected, type: `remove` });
-    selected = single ? `` : [];
+    selected = [];
     searchText = ``;
 };
-const isDisabled = (option) => disabledOptions.includes(option);
-$: isSelected = (option) => {
-    if (!(selected?.length > 0))
-        return false; // nothing is selected if `selected` is the empty array or string
-    if (single)
-        return selected === option;
-    else
-        return selected.includes(option);
-};
+$: isSelected = (label) => selectedLabels.includes(label);
 const handleEnterAndSpaceKeys = (handler) => (event) => {
     if ([`Enter`, `Space`].includes(event.code)) {
         event.preventDefault();
@@ -129,31 +181,38 @@ const handleEnterAndSpaceKeys = (handler) => (event) => {
 };
 </script>
 
-<!-- z-index: 2 when showOptions is true ensures the ul.tokens of one <MultiSelect /> display above those of another following shortly after it -->
+<!-- z-index: 2 when showOptions is true ensures the ul.tokens of one <MultiSelect />
+display above those of another following shortly after it -->
 <div
+  {id}
   class="multiselect {outerDivClass}"
   class:readonly
-  class:single
-  style={showOptions ? `z-index: 2;` : ``}
-  on:mouseup|stopPropagation={() => setOptionsVisible(true)}>
-  <ExpandIcon height="14pt" style="padding-left: 1pt;" />
+  class:single={maxSelect == 1}
+  style={showOptions ? `z-index: 2;` : undefined}
+  on:mouseup|stopPropagation={() => setOptionsVisible(true)}
+  use:onClickOutside={() => setOptionsVisible(false)}
+  use:onClickOutside={() => dispatch(`blur`)}
+>
+  <ExpandIcon height="14pt" style="padding: 0 3pt 0 1pt;" />
   <ul class="tokens {ulTokensClass}">
-    {#if single}
+    {#if maxSelect == 1 && selected[0]?.label}
       <span on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}>
-        {selected}
+        {selected[0].label}
       </span>
-    {:else if selected?.length > 0}
-      {#each selected as tag}
+    {:else}
+      {#each selected as { label }}
         <li
           class={liTokenClass}
-          on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}>
-          {tag}
+          on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}
+        >
+          {label}
           {#if !readonly}
             <button
-              on:mouseup|stopPropagation={() => remove(tag)}
-              on:keydown={handleEnterAndSpaceKeys(() => remove(tag))}
+              on:mouseup|stopPropagation={() => remove(label)}
+              on:keydown={handleEnterAndSpaceKeys(() => remove(label))}
               type="button"
-              title="{removeBtnTitle} {tag}">
+              title="{removeBtnTitle} {label}"
+            >
               <CrossIcon height="12pt" />
             </button>
           {/if}
@@ -167,21 +226,23 @@ const handleEnterAndSpaceKeys = (handler) => (event) => {
       on:mouseup|self|stopPropagation={() => setOptionsVisible(true)}
       on:keydown={handleKeydown}
       on:focus={() => setOptionsVisible(true)}
-      on:blur={() => dispatch(`blur`)}
-      on:blur={() => setOptionsVisible(false)}
       {name}
-      placeholder={selected.length ? `` : placeholder} />
+      placeholder={selectedLabels.length ? `` : placeholder}
+    />
   </ul>
   {#if readonly}
     <ReadOnlyIcon height="14pt" />
-  {:else}
+  {:else if selected.length > 0}
+    {#if maxSelect !== null && maxSelect > 1}
+      <span style="padding: 0 3pt;">{maxSelectMsg(selected.length, maxSelect)}</span>
+    {/if}
     <button
       type="button"
       class="remove-all"
       title={removeAllTitle}
       on:mouseup|stopPropagation={removeAll}
       on:keydown={handleEnterAndSpaceKeys(removeAll)}
-      style={selected.length === 0 ? `display: none;` : ``}>
+    >
       <CrossIcon height="14pt" />
     </button>
   {/if}
@@ -190,20 +251,22 @@ const handleEnterAndSpaceKeys = (handler) => (event) => {
     <ul
       class="options {ulOptionsClass}"
       class:hidden={!showOptions}
-      transition:fly={{ duration: 300, y: 40 }}>
-      {#each filteredOptions as option}
+      transition:fly|local={{ duration: 300, y: 40 }}
+    >
+      {#each matchingOptions as { label, disabled, title = '', selectedTitle, disabledTitle = defaultDisabledTitle }}
         <li
           on:mouseup|preventDefault|stopPropagation
           on:mousedown|preventDefault|stopPropagation={() => {
-            if (isDisabled(option)) return
-
-            isSelected(option) ? remove(option) : add(option)
+            if (disabled) return
+            isSelected(label) ? remove(label) : add(label)
           }}
-          class:selected={isSelected(option)}
-          class:active={activeOption === option}
-          class:disabled={isDisabled(option)}
-          class={liOptionClass}>
-          {option}
+          class:selected={isSelected(label)}
+          class:active={activeOption?.label === label}
+          class:disabled
+          title={disabled ? disabledTitle : (isSelected(label) && selectedTitle) || title}
+          class={liOptionClass}
+        >
+          {label}
         </li>
       {:else}
         {noOptionsMsg}
@@ -222,6 +285,7 @@ const handleEnterAndSpaceKeys = (handler) => (event) => {
     min-height: 18pt;
     display: flex;
     cursor: text;
+    padding: 0 3pt;
   }
   :where(.multiselect:focus-within) {
     border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue));

package/MultiSelect.svelte.d.ts

@@ -1,15 +1,20 @@
 import { SvelteComponentTyped } from "svelte";
+import type { Option, Primitive, ProtoOption } from './';
 declare const __propDef: {
     props: {
-        selected: string[] | string;
+        selected?: Option[] | undefined;
+        selectedLabels?: Primitive[] | undefined;
+        selectedValues?: Primitive[] | undefined;
         maxSelect?: number | null | undefined;
+        maxSelectMsg?: ((current: number, max: number) => string) | undefined;
         readonly?: boolean | undefined;
-        placeholder?: string | undefined;
-        options: string[];
-        disabledOptions?: string[] | undefined;
+        options: ProtoOption[];
         input?: HTMLInputElement | null | undefined;
+        placeholder?: string | undefined;
         name?: string | undefined;
+        id?: string | undefined;
         noOptionsMsg?: string | undefined;
+        activeOption?: Option | null | undefined;
         outerDivClass?: string | undefined;
         ulTokensClass?: string | undefined;
         liTokenClass?: string | undefined;
@@ -17,6 +22,7 @@ declare const __propDef: {
         liOptionClass?: string | undefined;
         removeBtnTitle?: string | undefined;
         removeAllTitle?: string | undefined;
+        defaultDisabledTitle?: string | undefined;
     };
     events: {
         mouseup: MouseEvent;

package/actions.d.ts

@@ -0,0 +1,3 @@
+export declare function onClickOutside(node: HTMLElement, cb?: () => void): {
+    destroy(): void;
+};

package/actions.js

@@ -0,0 +1,16 @@
+export function onClickOutside(node, cb) {
+    const dispatchOnClickOutside = (event) => {
+        const clickWasOutside = node && !node.contains(event.target);
+        if (clickWasOutside && !event.defaultPrevented) {
+            node.dispatchEvent(new CustomEvent(`clickOutside`));
+            if (cb)
+                cb();
+        }
+    };
+    document.addEventListener(`click`, dispatchOnClickOutside);
+    return {
+        destroy() {
+            document.removeEventListener(`click`, dispatchOnClickOutside);
+        },
+    };
+}

package/icons/ChevronExpand.svelte

@@ -5,5 +5,6 @@ export let style = ``;
 
 <svg {width} {height} {style} fill="currentColor" viewBox="0 0 16 16">
   <path
-    d="M3.646 9.146a.5.5 0 0 1 .708 0L8 12.793l3.646-3.647a.5.5 0 0 1 .708.708l-4 4a.5.5 0 0 1-.708 0l-4-4a.5.5 0 0 1 0-.708zm0-2.292a.5.5 0 0 0 .708 0L8 3.207l3.646 3.647a.5.5 0 0 0 .708-.708l-4-4a.5.5 0 0 0-.708 0l-4 4a.5.5 0 0 0 0 .708z" />
+    d="M3.646 9.146a.5.5 0 0 1 .708 0L8 12.793l3.646-3.647a.5.5 0 0 1 .708.708l-4 4a.5.5 0 0 1-.708 0l-4-4a.5.5 0 0 1 0-.708zm0-2.292a.5.5 0 0 0 .708 0L8 3.207l3.646 3.647a.5.5 0 0 0 .708-.708l-4-4a.5.5 0 0 0-.708 0l-4 4a.5.5 0 0 0 0 .708z"
+  />
 </svg>

package/icons/Cross.svelte

@@ -5,5 +5,6 @@ export let style = ``;
 
 <svg {width} {height} {style} viewBox="0 0 20 20" fill="currentColor">
   <path
-    d="M10 1.6a8.4 8.4 0 100 16.8 8.4 8.4 0 000-16.8zm4.789 11.461L13.06 14.79 10 11.729l-3.061 3.06L5.21 13.06 8.272 10 5.211 6.939 6.94 5.211 10 8.271l3.061-3.061 1.729 1.729L11.728 10l3.061 3.061z" />
+    d="M10 1.6a8.4 8.4 0 100 16.8 8.4 8.4 0 000-16.8zm4.789 11.461L13.06 14.79 10 11.729l-3.061 3.06L5.21 13.06 8.272 10 5.211 6.939 6.94 5.211 10 8.271l3.061-3.061 1.729 1.729L11.728 10l3.061 3.061z"
+  />
 </svg>

package/icons/ReadOnly.svelte

@@ -6,5 +6,6 @@ export let style = ``;
 <svg {width} {height} {style} viewBox="0 0 24 24" fill="currentColor">
   <path fill="none" d="M0 0h24v24H0V0z" />
   <path
-    d="M14.48 11.95c.17.02.34.05.52.05 2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4c0 .18.03.35.05.52l3.43 3.43zm2.21 2.21L22.53 20H23v-2c0-2.14-3.56-3.5-6.31-3.84zM0 3.12l4 4V10H1v2h3v3h2v-3h2.88l2.51 2.51C9.19 15.11 7 16.3 7 18v2h9.88l4 4 1.41-1.41L1.41 1.71 0 3.12zM6.88 10H6v-.88l.88.88z" />
+    d="M14.48 11.95c.17.02.34.05.52.05 2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4c0 .18.03.35.05.52l3.43 3.43zm2.21 2.21L22.53 20H23v-2c0-2.14-3.56-3.5-6.31-3.84zM0 3.12l4 4V10H1v2h3v3h2v-3h2.88l2.51 2.51C9.19 15.11 7 16.3 7 18v2h9.88l4 4 1.41-1.41L1.41 1.71 0 3.12zM6.88 10H6v-.88l.88.88z"
+  />
 </svg>

package/icons/index.d.ts

@@ -0,0 +1,3 @@
+export { default as CrossIcon } from './Cross.svelte';
+export { default as ExpandIcon } from './ChevronExpand.svelte';
+export { default as ReadOnlyIcon } from './ReadOnly.svelte';

package/icons/index.js

@@ -0,0 +1,3 @@
+export { default as CrossIcon } from './Cross.svelte';
+export { default as ExpandIcon } from './ChevronExpand.svelte';
+export { default as ReadOnlyIcon } from './ReadOnly.svelte';

package/index.d.ts

@@ -1 +1,15 @@
 export { default } from './MultiSelect.svelte';
+export declare type Primitive = string | number;
+export declare type Option = {
+    label: Primitive;
+    value: Primitive;
+    title?: string;
+    disabled?: boolean;
+    preselected?: boolean;
+    disabledTitle?: string;
+    selectedTitle?: string;
+    [key: string]: unknown;
+};
+export declare type ProtoOption = Primitive | (Omit<Option, `value`> & {
+    value?: Primitive;
+});

package/package.json

@@ -5,33 +5,33 @@
   "homepage": "https://svelte-multiselect.netlify.app",
   "repository": "https://github.com/janosh/svelte-multiselect",
   "license": "MIT",
-  "version": "1.2.3",
+  "version": "2.0.0",
   "type": "module",
   "svelte": "MultiSelect.svelte",
   "bugs": {
     "url": "https://github.com/janosh/svelte-multiselect/issues"
   },
   "devDependencies": {
-    "@sveltejs/adapter-static": "^1.0.0-next.21",
-    "@sveltejs/kit": "^1.0.0-next.187",
-    "@typescript-eslint/eslint-plugin": "^5.1.0",
-    "@typescript-eslint/parser": "^5.1.0",
-    "eslint": "^8.0.1",
+    "@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",
     "hastscript": "^7.0.2",
     "mdsvex": "^0.9.8",
-    "prettier": "^2.4.1",
-    "prettier-plugin-svelte": "^2.4.0",
+    "prettier": "^2.5.1",
+    "prettier-plugin-svelte": "^2.5.1",
     "rehype-autolink-headings": "^6.1.0",
     "rehype-slug": "^5.0.0",
-    "svelte": "^3.44.0",
-    "svelte-check": "^2.2.7",
-    "svelte-preprocess": "^4.9.8",
-    "svelte-toc": "^0.1.9",
-    "svelte2tsx": "^0.4.7",
+    "svelte": "^3.44.3",
+    "svelte-check": "^2.2.11",
+    "svelte-preprocess": "^4.10.1",
+    "svelte-toc": "^0.1.10",
+    "svelte2tsx": "^0.4.12",
     "tslib": "^2.3.1",
-    "typescript": "^4.4.4",
-    "vite": "^2.6.10"
+    "typescript": "^4.5.4",
+    "vite": "^2.7.3"
   },
   "keywords": [
     "svelte",
@@ -46,6 +46,7 @@
   "exports": {
     "./package.json": "./package.json",
     "./MultiSelect.svelte": "./MultiSelect.svelte",
+    "./actions": "./actions.js",
     ".": "./index.js"
   }
 }

package/readme.md

@@ -20,7 +20,7 @@
 
 <!-- remove above in docs -->
 
-Keyboard-friendly, zero-dependency multi-select Svelte component.
+**Keyboard-friendly, zero-dependency multi-select Svelte component.**
 
 ## Key Features
 
@@ -29,7 +29,7 @@ Keyboard-friendly, zero-dependency multi-select Svelte component.
 - **Searchable:** start typing to filter options
 - **Tagging:** selected options are recorded as tags within the text input
 - **Server-side rendering:** no reliance on browser objects like `window` or `document`
-- **Configurable:** see section [props](#props)
+- **Configurable:** see [props](#props)
 - **No dependencies:** needs only Svelte as dev dependency
 - **Keyboard friendly** for mouse-less form completion
 
@@ -75,16 +75,21 @@ Full list of props/bindable variables for this component:
 
 <div class="table">
 
-| name              | default                             | description                                                                                                                                                                |
-| :---------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `options`         | N/A (required prop)                 | Array of strings that will be listed in the dropdown selection.                                                                                                            |
-| `maxSelect`       | `null`                              | `null` or positive integer to allow users to select as many as they like or a maximum number of options, respectively.                                                     |
-| `selected`        | `[]` (or `''` if `maxSelect === 1`) | Array of currently/pre-selected options when binding/passing as props respectively.                                                                                        |
-| `readonly`        | `false`                             | Disables the component. It will still be rendered but users won't be able to interact with it.                                                                             |
-| `placeholder`     | `''`                                | String shown in the text input when no option is selected.                                                                                                                 |
-| `disabledOptions` | `[]`                                | Array of strings to be disabled in the dropdown selection. Corresponding `<li>` elements in the dropdown list can be styled through the `ul.options li.disabled` selector. |
-| `input`           | `undefined`                         | Handle to the `<input>` DOM node.                                                                                                                                          |
-| `name`            | `''`                                | 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.                      |
+<!-- 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()`.                                                                                                                         |
 
 </div>
 
@@ -102,25 +107,15 @@ Full list of props/bindable variables for this component:
 ### Examples
 
 <!-- prettier-ignore -->
-- `on:add={(event) => console.log(event.detail.token)}`
-- `on:remove={(event) => console.log(event.detail.token)}`.
-- ``on:change={(event) => console.log(`${event.detail.type}: '${event.detail.token}'`)}``
+- `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:blur={yourFunctionHere}`
 
 ```svelte
 <MultiSelect
-  on:change={(e) => alert(`You ${e.detail.type}ed '${e.detail.token}'`)} />
-```
-
-## Want to contribute?
-
-To submit a PR, clone the repo, install dependencies and start the dev server to try out your changes first.
-
-```sh
-git clone https://github.com/janosh/svelte-multiselect
-cd svelte-multiselect
-yarn
-yarn dev
+  on:change={(e) => alert(`You ${e.detail.type}ed '${e.detail.token.label}'`)}
+/>
 ```
 
 ## Styling
@@ -179,14 +174,14 @@ This simplified version of the DOM structure of this component shows where these
 
 ### 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.
+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.
 
 ```css
 :global(.multiselect) {
   /* top-level wrapper div */
 }
 :global(.multiselect ul.tokens > li) {
-  /* the blue tags representing selected options with remove buttons inside the input */
+  /* selected options */
 }
 :global(.multiselect ul.tokens > li button),
 :global(.multiselect button.remove-all) {
@@ -196,7 +191,7 @@ You can alternatively style every part of this component with more fine-grained
   /* dropdown options */
 }
 :global(.multiselect ul.options li) {
-  /* dropdown options */
+  /* dropdown list of available options */
 }
 :global(.multiselect ul.options li.selected) {
   /* selected options in the dropdown list */
@@ -209,13 +204,24 @@ You can alternatively style every part of this component with more fine-grained
   /* probably not necessary to style this state in most cases */
 }
 :global(.multiselect ul.options li.active) {
-  /* active means element was navigated to with up/down arrow keys */
+  /* 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 element again */
+  /* both active and already selected, pressing enter now will deselect the item */
 }
 :global(.multiselect ul.options li.disabled) {
-  /* this option is one included in disabledOptions (see props above) */
+  /* options with disabled key set to true (see props above) */
 }
 ```
+
+## Want to contribute?
+
+To submit a PR, clone the repo, install dependencies and start the dev server to try out your changes.
+
+```sh
+git clone https://github.com/janosh/svelte-multiselect
+cd svelte-multiselect
+yarn
+yarn dev
+```