svelte-multiselect 7.1.0 → 8.0.0

package/MultiSelect.svelte

@@ -33,9 +33,9 @@ export let liSelectedClass = ``;
 export let loading = false;
 export let matchingOptions = [];
 export let maxSelect = null; // null means any number of options are selectable
-export let maxSelectMsg = null;
+export let maxSelectMsg = (current, max) => (max > 1 ? `${current}/${max}` : ``);
 export let name = null;
-export let noOptionsMsg = `No matching options`;
+export let noMatchingOptionsMsg = `No matching options`;
 export let open = false;
 export let options;
 export let outerDiv = null;
@@ -46,29 +46,22 @@ export let placeholder = null;
 export let removeAllTitle = `Remove all`;
 export let removeBtnTitle = `Remove`;
 export let required = false;
+export let resetFilterOnAdd = true;
 export let searchText = ``;
 export let selected = options
     ?.filter((op) => op?.preselected)
     .slice(0, maxSelect ?? undefined) ?? [];
-export let selectedLabels = [];
-export let selectedValues = [];
 export let sortSelected = false;
 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
 const get_label = (op) => (op instanceof Object ? op.label : op);
-// fallback on label if option is object and value is undefined
-const get_value = (op) => (op instanceof Object ? op.value ?? op.label : op);
-// selected and _selected are identical except if maxSelect=1, selected will be the single item (or null)
-// in _selected which will always be an array for easier component internals. selected then solves
-// https://github.com/janosh/svelte-multiselect/issues/86
-let _selected = (selected ?? []);
-$: selected = maxSelect === 1 ? _selected[0] ?? null : _selected;
+// 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
+// https://github.com/janosh/svelte-multiselect/issues/136
+$: value = maxSelect === 1 ? selected[0] ?? null : selected;
 let wiggle = false; // controls wiggle animation when user tries to exceed maxSelect
-$: _selectedLabels = _selected?.map(get_label) ?? [];
-$: selectedLabels = maxSelect === 1 ? _selectedLabels[0] ?? null : _selectedLabels;
-$: _selectedValues = _selected?.map(get_value) ?? [];
-$: selectedValues = maxSelect === 1 ? _selectedValues[0] ?? null : _selectedValues;
 if (!(options?.length > 0)) {
     if (allowUserOptions) {
         options = []; // initializing as array avoids errors when component mounts
@@ -84,19 +77,14 @@ if (parseLabelsAsHtml && allowUserOptions) {
 if (maxSelect !== null && maxSelect < 1) {
     console.error(`maxSelect must be null or positive integer, got ${maxSelect}`);
 }
-if (!Array.isArray(_selected)) {
-    console.error(`internal variable _selected prop should always be an array, got ${_selected}`);
+if (!Array.isArray(selected)) {
+    console.error(`internal variable selected prop should always be an array, got ${selected}`);
 }
 const dispatch = createEventDispatcher();
 let add_option_msg_is_active = false; // controls active state of <li>{addOptionMsg}</li>
 let window_width;
-// formValue binds to input.form-control to prevent form submission if required
-// prop is true and no options are selected
-$: form_value = _selectedValues.join(`,`);
-$: if (form_value)
-    invalid = false; // reset error status whenever component state changes
 // options matching the current search text
-$: matchingOptions = options.filter((op) => filterFunc(op, searchText) && !_selectedLabels.includes(get_label(op)) // remove already selected options from dropdown list
+$: matchingOptions = options.filter((op) => filterFunc(op, searchText) && !selected.map(get_label).includes(get_label(op)) // remove already selected options from dropdown list
 );
 // raise if matchingOptions[activeIndex] does not yield a value
 if (activeIndex !== null && !matchingOptions[activeIndex]) {
@@ -106,12 +94,12 @@ if (activeIndex !== null && !matchingOptions[activeIndex]) {
 $: activeOption = activeIndex !== null ? matchingOptions[activeIndex] : null;
 // add an option to selected list
 function add(label, event) {
-    if (maxSelect && maxSelect > 1 && _selected.length >= maxSelect)
+    if (maxSelect && maxSelect > 1 && selected.length >= maxSelect)
         wiggle = true;
-    if (!isNaN(Number(label)) && typeof _selectedLabels[0] === `number`)
+    if (!isNaN(Number(label)) && typeof selected.map(get_label)[0] === `number`)
         label = Number(label); // convert to number if possible
-    const is_duplicate = _selected.some((option) => duplicateFunc(option, label));
-    if ((maxSelect === null || maxSelect === 1 || _selected.length < maxSelect) &&
+    const is_duplicate = selected.some((option) => duplicateFunc(option, label));
+    if ((maxSelect === null || maxSelect === 1 || selected.length < maxSelect) &&
         (duplicates || !is_duplicate)) {
         // first check if we find option in the options list
         let option = options.find((op) => get_label(op) === label);
@@ -140,29 +128,30 @@ function add(label, event) {
         if (option === undefined) {
             throw `Run time error, option with label ${label} not found in options list`;
         }
-        searchText = ``; // reset search string on selection
+        if (resetFilterOnAdd)
+            searchText = ``; // reset search string on selection
         if ([``, undefined, null].includes(option)) {
             console.error(`MultiSelect: encountered missing option with label ${label} (or option is poorly labeled)`);
             return;
         }
         if (maxSelect === 1) {
             // for maxselect = 1 we always replace current option with new one
-            _selected = [option];
+            selected = [option];
         }
         else {
-            _selected = [..._selected, option];
+            selected = [...selected, option];
             if (sortSelected === true) {
-                _selected = _selected.sort((op1, op2) => {
+                selected = selected.sort((op1, op2) => {
                     const [label1, label2] = [get_label(op1), get_label(op2)];
                     // coerce to string if labels are numbers
                     return `${label1}`.localeCompare(`${label2}`);
                 });
             }
             else if (typeof sortSelected === `function`) {
-                _selected = _selected.sort(sortSelected);
+                selected = selected.sort(sortSelected);
             }
         }
-        if (_selected.length === maxSelect)
+        if (selected.length === maxSelect)
             close_dropdown(event);
         else if (focusInputOnSelect === true ||
             (focusInputOnSelect === `desktop` && window_width > breakpoint)) {
@@ -170,14 +159,15 @@ function add(label, event) {
         }
         dispatch(`add`, { option });
         dispatch(`change`, { option, type: `add` });
+        invalid = false; // reset error status whenever new items are selected
     }
 }
 // remove an option from selected list
 function remove(label) {
-    if (_selected.length === 0)
+    if (selected.length === 0)
         return;
-    _selected.splice(_selectedLabels.lastIndexOf(label), 1);
-    _selected = _selected; // Svelte rerender after in-place splice
+    selected.splice(selected.map(get_label).lastIndexOf(label), 1);
+    selected = selected; // Svelte rerender after in-place splice
     const option = options.find((option) => get_label(option) === label) ??
         // if option with label could not be found but allowUserOptions is truthy,
         // assume it was created by user and create correspondidng option object
@@ -188,6 +178,7 @@ function remove(label) {
     }
     dispatch(`remove`, { option });
     dispatch(`change`, { option, type: `remove` });
+    invalid = false; // reset error status whenever items are removed
 }
 function open_dropdown(event) {
     if (disabled)
@@ -217,7 +208,7 @@ async function handle_keydown(event) {
         event.preventDefault(); // prevent enter key from triggering form submission
         if (activeOption) {
             const label = get_label(activeOption);
-            selectedLabels?.includes(label) ? remove(label) : add(label, event);
+            selected.map(get_label).includes(label) ? remove(label) : add(label, event);
             searchText = ``;
         }
         else if (allowUserOptions && searchText.length > 0) {
@@ -264,17 +255,17 @@ async function handle_keydown(event) {
         }
     }
     // on backspace key: remove last selected option
-    else if (event.key === `Backspace` && _selectedLabels.length > 0 && !searchText) {
-        remove(_selectedLabels.at(-1));
+    else if (event.key === `Backspace` && selected.length > 0 && !searchText) {
+        remove(selected.map(get_label).at(-1));
     }
 }
 function remove_all() {
-    dispatch(`removeAll`, { options: _selected });
-    dispatch(`change`, { options: _selected, type: `removeAll` });
-    _selected = [];
+    dispatch(`removeAll`, { options: selected });
+    dispatch(`change`, { options: selected, type: `removeAll` });
+    selected = [];
     searchText = ``;
 }
-$: is_selected = (label) => _selectedLabels.includes(label);
+$: is_selected = (label) => selected.map(get_label).includes(label);
 const if_enter_or_space = (handler) => (event) => {
     if ([`Enter`, `Space`].includes(event.code)) {
         event.preventDefault();
@@ -307,10 +298,10 @@ function on_click_outside(event) {
   title={disabled ? disabledInputTitle : null}
   aria-disabled={disabled ? `true` : null}
 >
-  <!-- formValue binds to input.form-control to prevent form submission if required prop is true and no options are selected -->
+  <!-- bind:value={selected} prevents form submission if required prop is true and no options are selected -->
   <input
     {required}
-    bind:value={form_value}
+    bind:value={selected}
     tabindex="-1"
     aria-hidden="true"
     aria-label="ignore this, used only to prevent form submission if select is required but empty"
@@ -319,7 +310,7 @@ function on_click_outside(event) {
   />
   <ExpandIcon width="15px" style="min-width: 1em; padding: 0 1pt;" />
   <ul class="selected {ulSelectedClass}">
-    {#each _selected as option, idx}
+    {#each selected as option, idx}
       <li class={liSelectedClass} aria-selected="true">
         <slot name="selected" {option} {idx}>
           {#if parseLabelsAsHtml}
@@ -357,7 +348,7 @@ function on_click_outside(event) {
         {disabled}
         {inputmode}
         {pattern}
-        placeholder={_selected.length == 0 ? placeholder : null}
+        placeholder={selected.length == 0 ? placeholder : null}
         aria-invalid={invalid ? `true` : null}
         on:blur
         on:change
@@ -384,16 +375,15 @@ function on_click_outside(event) {
     <slot name="disabled-icon">
       <DisabledIcon width="15px" />
     </slot>
-  {:else if _selected.length > 0}
+  {:else if selected.length > 0}
     {#if maxSelect && (maxSelect > 1 || maxSelectMsg)}
       <Wiggle bind:wiggle angle={20}>
         <span style="padding: 0 3pt;">
-          {maxSelectMsg?.(_selected.length, maxSelect) ??
-            (maxSelect > 1 ? `${_selected.length}/${maxSelect}` : ``)}
+          {maxSelectMsg?.(selected.length, maxSelect)}
         </span>
       </Wiggle>
     {/if}
-    {#if maxSelect !== 1 && _selected.length > 1}
+    {#if maxSelect !== 1 && selected.length > 1}
       <button
         type="button"
         class="remove-all"
@@ -423,7 +413,7 @@ function on_click_outside(event) {
         <li
           on:mousedown|stopPropagation
           on:mouseup|stopPropagation={(event) => {
-            if (!disabled) is_selected(label) ? remove(label) : add(label, event)
+            if (!disabled) add(label, event)
           }}
           title={disabled
             ? disabledTitle
@@ -463,12 +453,12 @@ function on_click_outside(event) {
             on:blur={() => (add_option_msg_is_active = false)}
             aria-selected="false"
           >
-            {!duplicates && _selected.some((option) => duplicateFunc(option, searchText))
+            {!duplicates && selected.some((option) => duplicateFunc(option, searchText))
               ? duplicateOptionMsg
               : addOptionMsg}
           </li>
         {:else}
-          <span>{noOptionsMsg}</span>
+          <span>{noMatchingOptionsMsg}</span>
         {/if}
       {/each}
     </ul>

package/MultiSelect.svelte.d.ts

@@ -30,7 +30,7 @@ declare const __propDef: {
         maxSelect?: number | null | undefined;
         maxSelectMsg?: ((current: number, max: number) => string) | null | undefined;
         name?: string | null | undefined;
-        noOptionsMsg?: string | undefined;
+        noMatchingOptionsMsg?: string | undefined;
         open?: boolean | undefined;
         options: Option[];
         outerDiv?: HTMLDivElement | null | undefined;
@@ -41,13 +41,13 @@ declare const __propDef: {
         removeAllTitle?: string | undefined;
         removeBtnTitle?: string | undefined;
         required?: boolean | undefined;
+        resetFilterOnAdd?: boolean | undefined;
         searchText?: string | undefined;
-        selected?: Option | Option[] | null | undefined;
-        selectedLabels?: string | number | (string | number)[] | null | undefined;
-        selectedValues?: unknown[] | unknown | null;
+        selected?: Option[] | undefined;
         sortSelected?: boolean | ((op1: Option, op2: Option) => number) | undefined;
         ulOptionsClass?: string | undefined;
         ulSelectedClass?: string | undefined;
+        value?: Option | Option[] | null | undefined;
     };
     slots: {
         selected: {

package/package.json

@@ -5,39 +5,40 @@
   "homepage": "https://svelte-multiselect.netlify.app",
   "repository": "https://github.com/janosh/svelte-multiselect",
   "license": "MIT",
-  "version": "7.1.0",
+  "version": "8.0.0",
   "type": "module",
   "svelte": "index.js",
   "main": "index.js",
   "bugs": "https://github.com/janosh/svelte-multiselect/issues",
   "devDependencies": {
-    "@playwright/test": "^1.26.0",
-    "@sveltejs/adapter-static": "^1.0.0-next.43",
-    "@sveltejs/kit": "^1.0.0-next.502",
+    "@iconify/svelte": "^3.0.0",
+    "@playwright/test": "^1.27.1",
+    "@sveltejs/adapter-static": "^1.0.0-next.44",
+    "@sveltejs/kit": "^1.0.0-next.516",
     "@sveltejs/package": "^1.0.0-next.5",
-    "@sveltejs/vite-plugin-svelte": "^1.0.8",
-    "@typescript-eslint/eslint-plugin": "^5.38.0",
-    "@typescript-eslint/parser": "^5.38.0",
-    "eslint": "^8.24.0",
+    "@sveltejs/vite-plugin-svelte": "^1.0.9",
+    "@typescript-eslint/eslint-plugin": "^5.40.0",
+    "@typescript-eslint/parser": "^5.40.0",
+    "eslint": "^8.25.0",
     "eslint-plugin-svelte3": "^4.0.0",
-    "hastscript": "^7.0.2",
-    "jsdom": "^20.0.0",
+    "hastscript": "^7.1.0",
+    "jsdom": "^20.0.1",
     "mdsvex": "^0.10.6",
     "prettier": "^2.7.1",
-    "prettier-plugin-svelte": "^2.7.0",
+    "prettier-plugin-svelte": "^2.8.0",
     "rehype-autolink-headings": "^6.1.1",
     "rehype-slug": "^5.0.1",
     "sass": "^1.55.0",
-    "svelte": "^3.50.1",
-    "svelte-check": "^2.9.0",
+    "svelte": "^3.52.0",
+    "svelte-check": "^2.9.2",
     "svelte-github-corner": "^0.1.0",
     "svelte-preprocess": "^4.10.6",
     "svelte-toc": "^0.4.0",
-    "svelte2tsx": "^0.5.18",
+    "svelte2tsx": "^0.5.20",
     "tslib": "^2.4.0",
-    "typescript": "^4.8.3",
-    "vite": "^3.1.3",
-    "vitest": "^0.23.4"
+    "typescript": "^4.8.4",
+    "vite": "^3.1.8",
+    "vitest": "^0.24.3"
   },
   "keywords": [
     "svelte",

package/readme.md

@@ -8,8 +8,8 @@
 [![Tests](https://github.com/janosh/svelte-multiselect/actions/workflows/test.yml/badge.svg)](https://github.com/janosh/svelte-multiselect/actions/workflows/test.yml)
 [![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?logo=NPM&color=purple)](https://npmjs.com/package/svelte-multiselect)
-[![Needs Svelte version](https://img.shields.io/npm/dependency-version/svelte-multiselect/dev/svelte?color=teal)](https://github.com/sveltejs/svelte/blob/master/CHANGELOG.md)
-[![REPL](https://img.shields.io/badge/Svelte-REPL-blue?logo=Svelte)](https://svelte.dev/repl/a5a14b8f15d64cb083b567292480db05)
+[![Needs Svelte version](https://img.shields.io/npm/dependency-version/svelte-multiselect/dev/svelte?color=teal&logo=Svelte&label=Svelte)](https://github.com/sveltejs/svelte/blob/master/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)
 
 </h4>
@@ -36,12 +36,14 @@
 
 ## Recent breaking changes
 
-- **v5.0.0** Supports both simple and object options. Previously strings and numbers were converted to `{ value, label }` objects internally and returned by `bind:selected`. Now, if you pass in `string[]`, that's exactly what you'll get from `bind:selected`. See [PR 76](https://github.com/janosh/svelte-multiselect/pull/76).
-- **v6.0.0** The prop `showOptions` which controls whether the list of dropdown options is currently open or closed was renamed to `open`. See [PR 103](https://github.com/janosh/svelte-multiselect/pull/103).
-- **v6.0.1** The prop `disabledTitle` which sets the title of the `<MultiSelect>` `<input>` node if in `disabled` mode was renamed to `disabledInputTitle`. See [PR 105](https://github.com/janosh/svelte-multiselect/pull/105).
-- **v6.0.1** The default margin of `1em 0` on the wrapper `div.multiselect` was removed. Instead, there is now a new CSS variable `--sms-margin`. Set it to `--sms-margin: 1em 0;` to restore the old appearance. See [PR 105](https://github.com/janosh/svelte-multiselect/pull/105).
-- **6.1.0** The `dispatch` events `focus` and `blur` were renamed to `open` and `close`, respectively. These actions refer to the dropdown list, i.e. `<MultiSelect on:open={(event) => console.log(event)}>` will trigger when the dropdown list opens. The focus and blur events are now regular DOM (not Svelte `dispatch`) events emitted by the `<input>` node. See [PR 120](https://github.com/janosh/svelte-multiselect/pull/120).
-- **v7.0.0** `selected` (as well `selectedLabels` and `selectedValues`) used to be arrays always. Now, if `maxSelect=1`, they will no longer be a length-1 array but simply a single a option (label/value respectively) or `null` if no option is selected. See [PR 123](https://github.com/janosh/svelte-multiselect/pull/123).
+- **v6.0.0**&nbsp; The prop `showOptions` which controls whether the list of dropdown options is currently open or closed was renamed to `open`. See [PR 103](https://github.com/janosh/svelte-multiselect/pull/103).
+- **v6.0.1**&nbsp; The prop `disabledTitle` which sets the title of the `<MultiSelect>` `<input>` node if in `disabled` mode was renamed to `disabledInputTitle`. See [PR 105](https://github.com/janosh/svelte-multiselect/pull/105).
+- **v6.0.1**&nbsp; The default margin of `1em 0` on the wrapper `div.multiselect` was removed. Instead, there is now a new CSS variable `--sms-margin`. Set it to `--sms-margin: 1em 0;` to restore the old appearance. See [PR 105](https://github.com/janosh/svelte-multiselect/pull/105).
+- **6.1.0**&nbsp; The `dispatch` events `focus` and `blur` were renamed to `open` and `close`, respectively. These actions refer to the dropdown list, i.e. `<MultiSelect on:open={(event) => console.log(event)}>` will trigger when the dropdown list opens. The focus and blur events are now regular DOM (not Svelte `dispatch`) events emitted by the `<input>` node. See [PR 120](https://github.com/janosh/svelte-multiselect/pull/120).
+- **v7.0.0**&nbsp; `selected` (as well `selectedLabels` and `selectedValues`) used to be arrays always. Now, if `maxSelect=1`, they will no longer be a length-1 array but simply a single a option (label/value respectively) or `null` if no option is selected. See [PR 123](https://github.com/janosh/svelte-multiselect/pull/123).
+- **8.0.0**&nbsp;
+  - 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. See [PR 138](https://github.com/janosh/svelte-multiselect/pull/138)
+  - Prop `noOptionsMsg` was renamed to `noMatchingOptionsMsg`. See [PR 133](https://github.com/janosh/svelte-multiselect/pull/133).
 
 ## Installation
 
@@ -216,7 +218,10 @@ import type { Option } from 'svelte-multiselect'
    Positive integer to limit the number of options users can pick. `null` means no limit. `maxSelect={1}` will change the type of `selected` to be a single `Option` (or `null`) (not a length-1 array). Likewise, the type of `selectedLabels` changes from `(string | number)[]` to `string | number | null` and `selectedValues` from `unknown[]` to `unknown | null`. `maxSelect={1}` will also give `div.multiselect` a class of `single`. I.e. you can target the selector `div.multiselect.single` to give single selects a different appearance from multi selects.
 
 1. ```ts
-   maxSelectMsg: ((current: number, max: number) => string) | null = null
+   maxSelectMsg: ((current: number, max: number) => string) | null = (
+    current: number,
+    max: number
+  ) => (max > 1 ? `${current}/${max}` : ``)
    ```
 
    Inform users how many of the maximum allowed options they have already selected. Set `maxSelectMsg={null}` to not show a message. Defaults to `null` when `maxSelect={1}` or `maxSelect={null}`. Else if `maxSelect > 1`, defaults to:
@@ -232,7 +237,7 @@ import type { Option } from 'svelte-multiselect'
    Applied to the `<input>` element. 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>` node.
 
 1. ```ts
-   noOptionsMsg: string = `No matching options`
+   noMatchingOptionsMsg: string = `No matching options`
    ```
 
    What message to show if no options match the user-entered search string.
@@ -291,6 +296,12 @@ import type { Option } from 'svelte-multiselect'
 
    Whether forms can be submitted without selecting any options. Aborts submission, is scrolled into view and shows help "Please fill out" message when true and user tries to submit with no options selected.
 
+1. ```ts
+   resetFilterOnAdd: boolean = true
+   ```
+
+   Whether text entered into the input to filter options in the dropdown list is reset to empty string when user selects an option.
+
 1. ```ts
    searchText: string = ``
    ```
@@ -298,31 +309,25 @@ import type { Option } from 'svelte-multiselect'
    Text the user-entered to filter down on the list of options. Binds both ways, i.e. can also be used to set the input text.
 
 1. ```ts
-   selected: Option[] | Option | null =
+   selected: Option[] =
     options
       ?.filter((op) => (op as ObjectOption)?.preselected)
       .slice(0, maxSelect ?? undefined) ?? []
    ```
 
-   Array of currently selected options. Supports 2-way binding `bind:selected={[1, 2, 3]}` to control component state externally or passed as prop to set pre-selected options that will already be populated when component mounts before any user interaction. If `maxSelect={1}`, selected will not be an array but a single `Option` or `null` if no options are selected.
-
-1. ```ts
-   selectedLabels: (string | number)[] | string | number | null = []
-   ```
-
-   Labels of currently selected options. Exposed just for convenience, equivalent to `selected.map(op => op.label)` when options are objects. If options are simple strings (or numbers), `selected === selectedLabels`. Supports binding but is read-only, i.e. since this value is reactive to `selected`, you cannot control `selected` by changing `bind:selectedLabels`. If `maxSelect={1}`, selectedLabels will not be an array but a single `string | number` or `null` if no options are selected.
+   Array of currently selected options. Supports 2-way binding `bind:selected={[1, 2, 3]}` to control component state externally. Can be passed as prop to set pre-selected options that will already be populated when component mounts before any user interaction.
 
 1. ```ts
-   selectedValues: unknown[] | unknown | null = []
+   sortSelected: boolean | ((op1: Option, op2: Option) => number) = false
    ```
 
-   Values of currently selected options. Exposed just for convenience, equivalent to `selected.map(op => op.value)` when options are objects. If options are simple strings (or numbers), `selected === selectedValues`. Supports binding but is read-only, i.e. since this value is reactive to `selected`, you cannot control `selected` by changing `bind:selectedValues`. If `maxSelect={1}`, selectedLabels will not be an array but a single value or `null` if no options are selected.
+   Default behavior is to render selected items in the order they were chosen. `sortSelected={true}` uses default JS array sorting. A compare function enables custom logic for sorting selected options. See the [`/sort-selected`](https://svelte-multiselect.netlify.app/sort-selected) example.
 
 1. ```ts
-   sortSelected: boolean | ((op1: Option, op2: Option) => number) = false
+   value: Option | Option[] | null = null
    ```
 
-   Default behavior is to render selected items in the order they were chosen. `sortSelected={true}` uses default JS array sorting. A compare function enables custom logic for sorting selected options. See the [`/sort-selected`](https://svelte-multiselect.netlify.app/sort-selected) example.
+   If `maxSelect={1}`, `value` will be the single item in `selected` (or `null` if `selected` is empty). If `maxSelect != 1`, `maxSelect` and `selected` are equal. Warning: `value` supports 1-way binding only, meaning `bind:value` will update `value` when internal component state changes but changing `value` externally will not update internal component state. This is because `value` is already reactive to `selected` and making `selected` reactive to `value` would be cyclic. Suggestions for better solutions that solve both [#86](https://github.com/janosh/svelte-multiselect/issues/86) and [#136](https://github.com/janosh/svelte-multiselect/issues/136) welcome!
 
 ## Slots