svelte-multiselect 11.3.0 → 11.4.0

package/dist/MultiSelect.svelte

@@ -1,9 +1,10 @@
-<script lang="ts" generics="Option extends import('./types').Option">import { tick } from 'svelte';
+<!-- eslint-disable-next-line @stylistic/quotes -- TS generics require string literals -->
+<script lang="ts" generics="Option extends import('./types').Option">import { tick, untrack } from 'svelte';
 import { flip } from 'svelte/animate';
 import { highlight_matches } from './attachments';
 import CircleSpinner from './CircleSpinner.svelte';
 import Icon from './Icon.svelte';
-import { fuzzy_match, get_label, get_style } from './utils';
+import { fuzzy_match, get_label, get_style, is_object } from './utils';
 import Wiggle from './Wiggle.svelte';
 let { activeIndex = $bindable(null), activeOption = $bindable(null), createOptionMsg = `Create this option...`, allowUserOptions = false, allowEmpty = false, autocomplete = `off`, autoScroll = true, breakpoint = 800, defaultDisabledTitle = `This option is disabled`, disabled = false, disabledInputTitle = `This input is disabled`, duplicateOptionMsg = `This option is already selected`, duplicates = false, keepSelectedInDropdown = false, key = (opt) => `${get_label(opt)}`.toLowerCase(), filterFunc = (opt, searchText) => {
     if (!searchText)
@@ -12,83 +13,145 @@ let { activeIndex = $bindable(null), activeOption = $bindable(null), createOptio
     return fuzzy
         ? fuzzy_match(searchText, label)
         : label.toLowerCase().includes(searchText.toLowerCase());
-}, fuzzy = true, closeDropdownOnSelect = `if-mobile`, form_input = $bindable(null), highlightMatches = true, id = null, input = $bindable(null), inputClass = ``, inputStyle = null, inputmode = null, invalid = $bindable(false), liActiveOptionClass = ``, liActiveUserMsgClass = ``, liOptionClass = ``, liOptionStyle = null, liSelectedClass = ``, liSelectedStyle = null, liUserMsgClass = ``, loading = false, matchingOptions = $bindable([]), maxOptions = undefined, maxSelect = null, maxSelectMsg = (current, max) => (max > 1 ? `${current}/${max}` : ``), maxSelectMsgClass = ``, name = null, noMatchingOptionsMsg = `No matching options`, open = $bindable(false), options = $bindable(), outerDiv = $bindable(null), outerDivClass = ``, parseLabelsAsHtml = false, pattern = null, placeholder = null, removeAllTitle = `Remove all`, removeBtnTitle = `Remove`, minSelect = null, required = false, resetFilterOnAdd = true, searchText = $bindable(``), value = $bindable(null), selected = $bindable(value !== null && value !== undefined
+}, fuzzy = true, closeDropdownOnSelect = false, form_input = $bindable(null), highlightMatches = true, id = null, input = $bindable(null), inputClass = ``, inputStyle = null, inputmode = null, invalid = $bindable(false), liActiveOptionClass = ``, liActiveUserMsgClass = ``, liOptionClass = ``, liOptionStyle = null, liSelectedClass = ``, liSelectedStyle = null, liUserMsgClass = ``, loading = false, matchingOptions = $bindable([]), maxOptions = undefined, maxSelect = $bindable(null), maxSelectMsg = (current, max) => (max > 1 ? `${current}/${max}` : ``), maxSelectMsgClass = ``, name = null, noMatchingOptionsMsg = `No matching options`, open = $bindable(false), options = $bindable(), outerDiv = $bindable(null), outerDivClass = ``, parseLabelsAsHtml = false, pattern = null, placeholder = null, removeAllTitle = `Remove all`, removeBtnTitle = `Remove`, minSelect = null, required = false, resetFilterOnAdd = true, searchText = $bindable(``), value = $bindable(null), selected = $bindable(value !== null && value !== undefined
     ? (Array.isArray(value) ? value : [value])
     : (options
-        ?.filter((opt) => opt instanceof Object && opt?.preselected)
-        .slice(0, maxSelect ?? undefined) ?? [])), sortSelected = false, selectedOptionsDraggable = !sortSelected, style = null, ulOptionsClass = ``, ulSelectedClass = ``, ulSelectedStyle = null, ulOptionsStyle = null, expandIcon, selectedItem, children, removeIcon, afterInput, spinner, disabledIcon, option, userMsg, onblur, onclick, onfocus, onkeydown, onkeyup, onmousedown, onmouseenter, onmouseleave, ontouchcancel, ontouchend, ontouchmove, ontouchstart, onadd, oncreate, onremove, onremoveAll, onchange, onopen, onclose, portal: portal_params = {}, ...rest } = $props();
+        ?.filter((opt) => typeof opt === `object` && opt !== null && opt?.preselected)
+        .slice(0, maxSelect ?? undefined) ?? [])), sortSelected = false, selectedOptionsDraggable = !sortSelected, style = null, ulOptionsClass = ``, ulSelectedClass = ``, ulSelectedStyle = null, ulOptionsStyle = null, expandIcon, selectedItem, children, removeIcon, afterInput, spinner, disabledIcon, option, userMsg, onblur, onclick, onfocus, onkeydown, onkeyup, onmousedown, onmouseenter, onmouseleave, ontouchcancel, ontouchend, ontouchmove, ontouchstart, onadd, oncreate, onremove, onremoveAll, onchange, onopen, onclose, onselectAll, portal: portal_params = {}, 
+// Select all feature
+selectAllOption = false, liSelectAllClass = ``, 
+// Dynamic options loading
+loadOptions, 
+// Animation parameters for selected options flip animation
+selectedFlipParams = { duration: 100 }, ...rest } = $props();
+// Extract loadOptions function and config (supports both simple function and config object)
+const load_options_fn = $derived(loadOptions
+    ? (typeof loadOptions === `function` ? loadOptions : loadOptions.fetch)
+    : null);
+const load_options_debounce_ms = $derived(loadOptions && typeof loadOptions === `object`
+    ? (loadOptions.debounceMs ?? 300)
+    : 300);
+const load_options_batch_size = $derived(loadOptions && typeof loadOptions === `object`
+    ? (loadOptions.batchSize ?? 50)
+    : 50);
+const load_options_on_open = $derived(loadOptions && typeof loadOptions === `object`
+    ? (loadOptions.onOpen ?? true)
+    : true);
+// Helper to compare arrays/values for equality to avoid unnecessary updates
+// Prevents infinite loops when value/selected are bound to reactive wrappers
+// that clone arrays on assignment (e.g. Superforms, Svelte stores). See issue #309.
+function values_equal(val1, val2) {
+    if (val1 === val2)
+        return true;
+    if (Array.isArray(val1) && Array.isArray(val2)) {
+        return val1.length === val2.length &&
+            val1.every((item, idx) => item === val2[idx]);
+    }
+    return false;
+}
+// Sync selected ↔ value bidirectionally. Use untrack to prevent each effect from
+// reacting to changes in the "destination" value, and values_equal to prevent
+// infinite loops with reactive wrappers that clone arrays. See issue #309.
 $effect.pre(() => {
-    // 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;
-}); // sync selected updates to value
+    const new_value = maxSelect === 1 ? (selected[0] ?? null) : selected;
+    if (!values_equal(untrack(() => value), new_value))
+        value = new_value;
+});
 $effect.pre(() => {
-    if (maxSelect === 1)
-        selected = value ? [value] : [];
-    else
-        selected = value ?? [];
-}); // sync value updates to selected
+    const new_selected = maxSelect === 1
+        ? (value ? [value] : [])
+        : (Array.isArray(value) ? value : []);
+    if (!values_equal(untrack(() => selected), new_selected))
+        selected = new_selected;
+});
 let wiggle = $state(false); // controls wiggle animation when user tries to exceed maxSelect
-if (!(options?.length > 0)) {
+let ignore_hover = $state(false); // ignore mouseover during keyboard navigation to prevent scroll-triggered hover
+// Internal state for loadOptions feature (null = never loaded)
+let loaded_options = $state([]);
+let load_options_has_more = $state(true);
+let load_options_loading = $state(false);
+let load_options_last_search = $state(null);
+let debounce_timer = null;
+let effective_options = $derived(loadOptions ? loaded_options : (options ?? []));
+// Cache selected keys and labels to avoid repeated .map() calls
+let selected_keys = $derived(selected.map(key));
+let selected_labels = $derived(selected.map(get_label));
+// Normalize placeholder prop (supports string or { text, persistent } object)
+const placeholder_text = $derived(typeof placeholder === `string` ? placeholder : placeholder?.text ?? null);
+const placeholder_persistent = $derived(typeof placeholder === `object` && placeholder?.persistent === true);
+// Helper to sort selected options (used by add() and select_all())
+function sort_selected(items) {
+    if (sortSelected === true) {
+        return items.toSorted((op1, op2) => `${get_label(op1)}`.localeCompare(`${get_label(op2)}`));
+    }
+    else if (typeof sortSelected === `function`) {
+        return items.toSorted(sortSelected);
+    }
+    return items;
+}
+if (!loadOptions && !((options?.length ?? 0) > 0)) {
     if (allowUserOptions || loading || disabled || allowEmpty) {
         options = []; // initializing as array avoids errors when component mounts
     }
     else {
         // error on empty options if user is not allowed to create custom options and loading is false
         // and component is not disabled and allowEmpty is false
-        console.error(`MultiSelect received no options`);
+        console.error(`MultiSelect: received no options`);
     }
 }
 if (maxSelect !== null && maxSelect < 1) {
-    console.error(`MultiSelect's maxSelect must be null or positive integer, got ${maxSelect}`);
+    console.error(`MultiSelect: maxSelect must be null or positive integer, got ${maxSelect}`);
 }
 if (!Array.isArray(selected)) {
-    console.error(`MultiSelect's selected prop should always be an array, got ${selected}`);
+    console.error(`MultiSelect: selected prop should always be an array, got ${selected}`);
 }
 if (maxSelect && typeof required === `number` && required > maxSelect) {
-    console.error(`MultiSelect maxSelect=${maxSelect} < required=${required}, makes it impossible for users to submit a valid form`);
+    console.error(`MultiSelect: maxSelect=${maxSelect} < required=${required}, makes it impossible for users to submit a valid form`);
 }
 if (parseLabelsAsHtml && allowUserOptions) {
-    console.warn(`Don't combine parseLabelsAsHtml and allowUserOptions. It's susceptible to XSS attacks!`);
+    console.warn(`MultiSelect: don't combine parseLabelsAsHtml and allowUserOptions. It's susceptible to XSS attacks!`);
 }
 if (sortSelected && selectedOptionsDraggable) {
-    console.warn(`MultiSelect's sortSelected and selectedOptionsDraggable should not be combined as any ` +
+    console.warn(`MultiSelect: sortSelected and selectedOptionsDraggable should not be combined as any ` +
         `user re-orderings of selected options will be undone by sortSelected on component re-renders.`);
 }
 if (allowUserOptions && !createOptionMsg && createOptionMsg !== null) {
-    console.error(`MultiSelect has allowUserOptions=${allowUserOptions} but createOptionMsg=${createOptionMsg} is falsy. ` +
+    console.error(`MultiSelect: 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}`);
+    console.error(`MultiSelect: maxOptions must be undefined or a positive integer, got ${maxOptions}`);
 }
 let option_msg_is_active = $state(false); // controls active state of <li>{createOptionMsg}</li>
 let window_width = $state(0);
 // options matching the current search text
 $effect.pre(() => {
-    matchingOptions = options.filter((opt) => filterFunc(opt, searchText) &&
+    // When using loadOptions, server handles filtering, so skip client-side filterFunc
+    const opts_to_filter = effective_options;
+    matchingOptions = opts_to_filter.filter((opt) => (loadOptions || filterFunc(opt, searchText)) &&
         // remove already selected options from dropdown list unless duplicate selections are allowed
         // or keepSelectedInDropdown is enabled
-        (!selected.map(key).includes(key(opt)) || duplicates ||
-            keepSelectedInDropdown));
+        (!selected_keys.includes(key(opt)) || duplicates || keepSelectedInDropdown));
+});
+// reset activeIndex if out of bounds (can happen when options change while dropdown is open)
+$effect(() => {
+    if (activeIndex !== null && !matchingOptions[activeIndex]) {
+        activeIndex = null;
+    }
 });
-// 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}`;
-}
 // update activeOption when activeIndex changes
 $effect(() => {
     activeOption = matchingOptions[activeIndex ?? -1] ?? null;
 });
+// Helper to check if removing an option would violate minSelect constraint
+const can_remove = $derived(minSelect === null || selected.length > minSelect);
 // toggle an option between selected and unselected states (for keepSelectedInDropdown mode)
 function toggle_option(option_to_toggle, event) {
-    const is_currently_selected = selected.map(key).includes(key(option_to_toggle));
+    const is_currently_selected = selected_keys.includes(key(option_to_toggle));
     if (is_currently_selected) {
-        if (minSelect === null || selected.length > minSelect) { // Only remove if it wouldn't violate minSelect
+        if (can_remove)
             remove(option_to_toggle, event);
-        }
     }
     else
         add(option_to_toggle, event);
@@ -98,25 +161,25 @@ function add(option_to_add, event) {
     event.stopPropagation();
     if (maxSelect !== null && selected.length >= maxSelect)
         wiggle = true;
-    if (!isNaN(Number(option_to_add)) && typeof selected.map(get_label)[0] === `number`) {
+    if (!isNaN(Number(option_to_add)) && typeof selected_labels[0] === `number`) {
         option_to_add = Number(option_to_add); // convert to number if possible
     }
-    const is_duplicate = selected.map(key).includes(key(option_to_add));
+    const is_duplicate = selected_keys.includes(key(option_to_add));
     if ((maxSelect === null || maxSelect === 1 || selected.length < maxSelect) &&
         (duplicates || !is_duplicate)) {
-        if (!options.includes(option_to_add) && // first check if we find option in the options list
+        if (!effective_options.includes(option_to_add) && // first check if we find option in the options list
             // this has the side-effect of not allowing to user to add the same
             // custom option twice in append mode
             [true, `append`].includes(allowUserOptions) &&
             searchText.length > 0) {
             // user entered text but no options match, so if allowUserOptions = true | 'append', we create
             // a new option from the user-entered text
-            if (typeof options[0] === `object`) {
+            if (typeof effective_options[0] === `object`) {
                 // if 1st option is an object, we create new option as object to keep type homogeneity
                 option_to_add = { label: searchText };
             }
             else {
-                if ([`number`, `undefined`].includes(typeof options[0]) &&
+                if ([`number`, `undefined`].includes(typeof effective_options[0]) &&
                     !isNaN(Number(searchText))) {
                     // create new option as number if it parses to a number and 1st option is also number or missing
                     option_to_add = Number(searchText);
@@ -127,46 +190,31 @@ function add(option_to_add, event) {
             }
             // Fire oncreate event for all user-created options, regardless of type
             oncreate?.({ option: option_to_add });
-            if (allowUserOptions === `append`)
-                options = [...options, option_to_add];
+            if (allowUserOptions === `append`) {
+                if (loadOptions) {
+                    loaded_options = [...loaded_options, option_to_add];
+                }
+                else {
+                    options = [...(options ?? []), option_to_add];
+                }
+            }
         }
         if (resetFilterOnAdd)
             searchText = ``; // reset search string on selection
         if ([``, undefined, null].includes(option_to_add)) {
-            console.error(`MultiSelect: encountered falsy option ${option_to_add}`);
+            console.error(`MultiSelect: encountered falsy option`, option_to_add);
             return;
         }
         // for maxSelect = 1 we always replace current option with new one
         if (maxSelect === 1)
             selected = [option_to_add];
         else {
-            selected = [...selected, option_to_add];
-            if (sortSelected === true) {
-                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);
-            }
-        }
-        const reached_max_select = selected.length >= (maxSelect ?? Infinity);
-        const dropdown_should_close = closeDropdownOnSelect === true ||
-            closeDropdownOnSelect === `retain-focus` ||
-            (closeDropdownOnSelect === `if-mobile` && window_width &&
-                window_width < breakpoint);
-        const should_retain_focus = closeDropdownOnSelect === `retain-focus`;
-        if (reached_max_select || dropdown_should_close) {
-            close_dropdown(event, should_retain_focus);
+            selected = sort_selected([...selected, option_to_add]);
         }
-        else if (!dropdown_should_close)
-            input?.focus();
+        clear_validity();
+        handle_dropdown_after_select(event);
         onadd?.({ option: option_to_add });
         onchange?.({ option: option_to_add, type: `add` });
-        invalid = false; // reset error status whenever new items are selected
-        form_input?.setCustomValidity(``);
     }
 }
 // remove an option from selected list
@@ -180,15 +228,15 @@ function remove(option_to_drop, event) {
         // if option with label could not be found but allowUserOptions is truthy,
         // assume it was created by user and create corresponding option object
         // on the fly for use as event payload
-        const other_ops_type = typeof options[0];
-        option_removed = (other_ops_type ? { label: option_to_drop } : option_to_drop);
+        const is_object_option = typeof effective_options[0] === `object`;
+        option_removed = (is_object_option ? { label: option_to_drop } : option_to_drop);
     }
     if (option_removed === undefined) {
-        return console.error(`Multiselect can't remove selected option ${JSON.stringify(option_to_drop)}, not found in selected list`);
+        console.error(`MultiSelect: can't remove option ${JSON.stringify(option_to_drop)}, not found in selected list`);
+        return;
     }
     selected = [...selected]; // trigger Svelte rerender
-    invalid = false; // reset error status whenever items are removed
-    form_input?.setCustomValidity(``);
+    clear_validity();
     onremove?.({ option: option_removed });
     onchange?.({ option: option_removed, type: `remove` });
 }
@@ -210,6 +258,52 @@ function close_dropdown(event, retain_focus = false) {
     activeIndex = null;
     onclose?.({ event });
 }
+function clear_validity() {
+    invalid = false;
+    form_input?.setCustomValidity(``);
+}
+function handle_dropdown_after_select(event) {
+    const reached_max = selected.length >= (maxSelect ?? Infinity);
+    const should_close = closeDropdownOnSelect === true ||
+        closeDropdownOnSelect === `retain-focus` ||
+        (closeDropdownOnSelect === `if-mobile` && window_width &&
+            window_width < breakpoint);
+    if (reached_max || should_close) {
+        close_dropdown(event, closeDropdownOnSelect === `retain-focus`);
+    }
+    else
+        input?.focus();
+}
+// Check if a user message (create option, duplicate warning, no match) is visible
+const has_user_msg = $derived(searchText.length > 0 && Boolean((allowUserOptions && createOptionMsg) ||
+    (!duplicates && selected_labels.includes(searchText)) ||
+    (matchingOptions.length === 0 && noMatchingOptionsMsg)));
+// Handle arrow key navigation through options (uses module-scope `has_user_msg`)
+async function handle_arrow_navigation(direction) {
+    ignore_hover = true;
+    // toggle user message when no options match but user can create
+    if (allowUserOptions && !matchingOptions.length && searchText.length > 0) {
+        option_msg_is_active = !option_msg_is_active;
+        return;
+    }
+    if (activeIndex === null && !matchingOptions.length)
+        return; // nothing to navigate
+    // activate first option or navigate with wrap-around
+    if (activeIndex === null) {
+        activeIndex = 0;
+    }
+    else {
+        const total = matchingOptions.length + (has_user_msg ? 1 : 0);
+        activeIndex = (activeIndex + direction + total) % total; // +total handles negative mod
+    }
+    // update active state based on new index
+    option_msg_is_active = has_user_msg && activeIndex === matchingOptions.length;
+    activeOption = option_msg_is_active ? null : matchingOptions[activeIndex] ?? null;
+    if (autoScroll) {
+        await tick();
+        document.querySelector(`ul.options > li.active`)?.scrollIntoViewIfNeeded?.();
+    }
+}
 // handle all keyboard events this component receives
 async function handle_keydown(event) {
     // on escape or tab out of input: close options dropdown and reset search text
@@ -217,20 +311,17 @@ async function handle_keydown(event) {
         event.stopPropagation();
         close_dropdown(event);
         searchText = ``;
-    } // on enter key: toggle active option and reset search text
+    } // on enter key: toggle active option
     else if (event.key === `Enter`) {
         event.stopPropagation();
         event.preventDefault(); // prevent enter key from triggering form submission
         if (activeOption) {
-            if (selected.includes(activeOption)) {
-                // Only remove if it wouldn't violate minSelect
-                if (minSelect === null || selected.length > minSelect) {
+            if (selected_keys.includes(key(activeOption))) {
+                if (can_remove)
                     remove(activeOption, event);
-                }
             }
             else
-                add(activeOption, event);
-            searchText = ``;
+                add(activeOption, event); // add() handles resetFilterOnAdd internally when successful
         }
         else if (allowUserOptions && searchText.length > 0) {
             // user entered text but no options match, so if allowUserOptions is truthy, we create new option
@@ -242,59 +333,14 @@ async function handle_keydown(event) {
             open_dropdown(event);
         }
     } // on up/down arrow keys: update active option
-    else if ([`ArrowDown`, `ArrowUp`].includes(event.key)) {
+    else if (event.key === `ArrowDown` || event.key === `ArrowUp`) {
         event.stopPropagation();
-        // if no option is active yet, but there are matching options, make first one active
-        if (activeIndex === null && matchingOptions.length > 0) {
-            event.preventDefault(); // Prevent scroll only if we handle the key
-            activeIndex = 0;
-            return;
-        }
-        else if (allowUserOptions && !matchingOptions.length && searchText.length > 0) {
-            event.preventDefault(); // Prevent scroll only if we handle the key
-            // if allowUserOptions is truthy and user entered text but no options match, we make
-            // <li>{addUserMsg}</li> active on keydown (or toggle it if already active)
-            option_msg_is_active = !option_msg_is_active;
-            return;
-        }
-        else if (activeIndex === null) {
-            // if no option is active and no options are matching, do nothing
-            return;
-        }
-        event.preventDefault(); // Prevent scroll only if we handle the key
-        // if none of the above special cases apply, we make next/prev option
-        // active with wrap around at both ends
-        const increment = event.key === `ArrowUp` ? -1 : 1;
-        // Include user message in total count if it exists
-        const has_user_msg = searchText && ((allowUserOptions && createOptionMsg) ||
-            (!duplicates && selected.map(get_label).includes(searchText)) ||
-            (matchingOptions.length === 0 && noMatchingOptionsMsg));
-        const total_items = matchingOptions.length + (has_user_msg ? 1 : 0);
-        activeIndex = (activeIndex + increment) % total_items;
-        // in JS % behaves like remainder operator, not real modulo, so negative numbers stay negative
-        // need to do manual wrap around at 0
-        if (activeIndex < 0)
-            activeIndex = total_items - 1;
-        // Handle user message activation
-        if (has_user_msg && activeIndex === matchingOptions.length) {
-            option_msg_is_active = true;
-            activeOption = null;
-        }
-        else {
-            option_msg_is_active = false;
-            activeOption = matchingOptions[activeIndex] ?? null;
-        }
-        if (autoScroll) {
-            await tick();
-            const li = document.querySelector(`ul.options > li.active`);
-            if (li)
-                li.scrollIntoViewIfNeeded?.();
-        }
+        event.preventDefault();
+        await handle_arrow_navigation(event.key === `ArrowUp` ? -1 : 1);
     } // on backspace key: remove last selected option
     else if (event.key === `Backspace` && selected.length > 0 && !searchText) {
         event.stopPropagation();
-        // Only remove option if it wouldn't violate minSelect
-        if (minSelect === null || selected.length > minSelect) {
+        if (can_remove) {
             const last_option = selected.at(-1);
             if (last_option)
                 remove(last_option, event);
@@ -314,21 +360,41 @@ function remove_all(event) {
         // If no minSelect constraint, remove all
         removed_options = selected;
         selected = [];
-        searchText = ``;
+        searchText = ``; // always clear on remove all (resetFilterOnAdd only applies to add operations)
     }
     else if (selected.length > minSelect) {
         // Keep the first minSelect items
         removed_options = selected.slice(minSelect);
         selected = selected.slice(0, minSelect);
-        searchText = ``;
+        searchText = ``; // always clear on remove all (resetFilterOnAdd only applies to add operations)
+    }
+    // Only fire events if something was actually removed
+    if (removed_options.length > 0) {
+        onremoveAll?.({ options: removed_options });
+        onchange?.({ options: selected, type: `removeAll` });
+    }
+}
+function select_all(event) {
+    event.stopPropagation();
+    const limit = maxSelect ?? Infinity;
+    // Use matchingOptions for "select all visible" semantics
+    const options_to_add = matchingOptions.filter((opt) => {
+        const is_disabled = is_object(opt) && opt.disabled;
+        return !is_disabled && !selected_keys.includes(key(opt));
+    }).slice(0, limit - selected.length);
+    if (options_to_add.length > 0) {
+        selected = sort_selected([...selected, ...options_to_add]);
+        if (resetFilterOnAdd)
+            searchText = ``;
+        clear_validity();
+        handle_dropdown_after_select(event);
+        onselectAll?.({ options: options_to_add });
+        onchange?.({ options: selected, type: `selectAll` });
     }
-    onremoveAll?.({ options: removed_options });
-    onchange?.({ options: selected, type: `removeAll` });
-    // If selected.length <= minSelect, do nothing (can't remove any more)
 }
-let is_selected = $derived((label) => selected.map(get_label).includes(label));
+let is_selected = $derived((label) => selected_labels.includes(label));
 const if_enter_or_space = (handler) => (event) => {
-    if ([`Enter`, `Space`].includes(event.code)) {
+    if (event.key === `Enter` || event.code === `Space`) {
         event.preventDefault();
         handler(event);
     }
@@ -466,6 +532,74 @@ function portal(node, params) {
         };
     }
 }
+// Dynamic options loading - captures search at call time to avoid race conditions
+async function load_dynamic_options(reset) {
+    if (!load_options_fn || load_options_loading || (!reset && !load_options_has_more)) {
+        return;
+    }
+    // Capture search term at call time to avoid race with user typing during fetch
+    const search = searchText;
+    const offset = reset ? 0 : loaded_options.length;
+    load_options_loading = true;
+    try {
+        const limit = load_options_batch_size;
+        const result = await load_options_fn({ search, offset, limit });
+        loaded_options = reset ? result.options : [...loaded_options, ...result.options];
+        load_options_has_more = result.hasMore;
+        load_options_last_search = search;
+    }
+    catch (err) {
+        console.error(`MultiSelect: loadOptions error:`, err);
+    }
+    finally {
+        load_options_loading = false;
+    }
+}
+// Single effect handles initial load + search changes
+$effect(() => {
+    if (!load_options_fn)
+        return;
+    // Reset state when dropdown closes so next open triggers fresh load
+    if (!open) {
+        load_options_last_search = null;
+        loaded_options = [];
+        load_options_has_more = true;
+        return;
+    }
+    if (debounce_timer)
+        clearTimeout(debounce_timer);
+    const search = searchText;
+    const is_first_load = load_options_last_search === null;
+    if (is_first_load) {
+        if (load_options_on_open) {
+            // Load immediately on dropdown open
+            load_dynamic_options(true);
+        }
+        else if (search) {
+            // onOpen=false but user typed - debounce and load
+            debounce_timer = setTimeout(() => load_dynamic_options(true), load_options_debounce_ms);
+        }
+        // If onOpen=false and no search text, do nothing (wait for user to type)
+    }
+    else if (search !== load_options_last_search) {
+        // Subsequent loads: debounce search changes
+        // Clear stale results immediately so UI doesn't show wrong results while loading
+        loaded_options = [];
+        load_options_has_more = true;
+        debounce_timer = setTimeout(() => load_dynamic_options(true), load_options_debounce_ms);
+    }
+    return () => {
+        if (debounce_timer)
+            clearTimeout(debounce_timer);
+    };
+});
+function handle_options_scroll(event) {
+    if (!load_options_fn || load_options_loading || !load_options_has_more)
+        return;
+    const { scrollTop, scrollHeight, clientHeight } = event.target;
+    if (scrollHeight - scrollTop - clientHeight <= 100)
+        load_dynamic_options(false);
+}
 </script>
 
 <svelte:window
@@ -525,7 +659,7 @@ function portal(node, params) {
     aria-label="selected options"
     style={ulSelectedStyle}
   >
-    {#each selected as option, idx (duplicates ? [key(option), idx] : key(option))}
+    {#each selected as option, idx (duplicates ? `${key(option)}-${idx}` : key(option))}
       {@const selectedOptionStyle =
         [get_style(option, `selected`), liSelectedStyle].filter(Boolean).join(
           ` `,
@@ -535,7 +669,7 @@ function portal(node, params) {
         class={liSelectedClass}
         role="option"
         aria-selected="true"
-        animate:flip={{ duration: 100 }}
+        animate:flip={selectedFlipParams}
         draggable={selectedOptionsDraggable && !disabled && selected.length > 1}
         ondragstart={dragstart(idx)}
         ondragover={(event) => {
@@ -545,6 +679,7 @@ function portal(node, params) {
         ondragenter={() => (drag_idx = idx)}
         class:active={drag_idx === idx}
         style={selectedOptionStyle}
+        onmouseup={(event) => event.stopPropagation()}
       >
         {#if selectedItem}
           {@render selectedItem({
@@ -561,7 +696,7 @@ function portal(node, params) {
         {:else}
           {get_label(option)}
         {/if}
-        {#if !disabled && (minSelect === null || selected.length > minSelect)}
+        {#if !disabled && can_remove}
           <button
             onclick={(event) => remove(option, event)}
             onkeydown={if_enter_or_space((event) => remove(option, event))}
@@ -588,7 +723,7 @@ function portal(node, params) {
       {autocomplete}
       {inputmode}
       {pattern}
-      placeholder={selected.length === 0 ? placeholder : null}
+      placeholder={selected.length === 0 || placeholder_persistent ? placeholder_text : null}
       aria-invalid={invalid ? `true` : null}
       ondrop={() => false}
       onmouseup={open_dropdown}
@@ -611,7 +746,7 @@ function portal(node, params) {
         disabled,
         invalid,
         id,
-        placeholder,
+        placeholder: placeholder_text,
         open,
         required,
       })}
@@ -660,7 +795,8 @@ function portal(node, params) {
   {/if}
 
   <!-- only render options dropdown if options or searchText is not empty (needed to avoid briefly flashing empty dropdown) -->
-  {#if (searchText && noMatchingOptionsMsg) || options?.length > 0}
+  {#if (searchText && noMatchingOptionsMsg) || effective_options.length > 0 ||
+      loadOptions}
     <ul
       use:portal={{ target_node: outerDiv, ...portal_params }}
       {@attach highlight_matches({
@@ -682,14 +818,30 @@ function portal(node, params) {
       aria-disabled={disabled ? `true` : null}
       bind:this={ul_options}
       style={ulOptionsStyle}
+      onscroll={handle_options_scroll}
+      onmousemove={() => (ignore_hover = false)}
     >
+      {#if selectAllOption && effective_options.length > 0 &&
+        (maxSelect === null || maxSelect > 1)}
+        {@const label = typeof selectAllOption === `string` ? selectAllOption : `Select all`}
+        <li
+          class="select-all {liSelectAllClass}"
+          onclick={select_all}
+          onkeydown={if_enter_or_space(select_all)}
+          role="option"
+          aria-selected="false"
+          tabindex="0"
+        >
+          {label}
+        </li>
+      {/if}
       {#each matchingOptions.slice(
         0,
         maxOptions == null ? Infinity : Math.max(0, maxOptions),
       ) as
         option_item,
         idx
-        (duplicates ? [key(option_item), idx] : key(option_item))
+        (duplicates ? `${key(option_item)}-${idx}` : key(option_item))
       }
         {@const {
         label,
@@ -697,7 +849,7 @@ function portal(node, params) {
         title = null,
         selectedTitle = null,
         disabledTitle = defaultDisabledTitle,
-      } = option_item instanceof Object ? option_item : { label: option_item }}
+      } = is_object(option_item) ? option_item : { label: option_item }}
         {@const active = activeIndex === idx}
         {@const selected = is_selected(label)}
         {@const optionStyle =
@@ -717,7 +869,7 @@ function portal(node, params) {
           class:disabled
           class="{liOptionClass} {active ? liActiveOptionClass : ``}"
           onmouseover={() => {
-            if (!disabled) activeIndex = idx
+            if (!disabled && !ignore_hover) activeIndex = idx
           }}
           onfocus={() => {
             if (!disabled) activeIndex = idx
@@ -760,18 +912,18 @@ function portal(node, params) {
         </li>
       {/each}
       {#if searchText}
-        {@const text_input_is_duplicate = selected.map(get_label).includes(searchText)}
+        {@const text_input_is_duplicate = selected_labels.includes(searchText)}
         {@const is_dupe = !duplicates && text_input_is_duplicate && `dupe`}
         {@const can_create = Boolean(allowUserOptions && createOptionMsg) && `create`}
         {@const no_match = Boolean(matchingOptions?.length === 0 && noMatchingOptionsMsg) &&
         `no-match`}
         {@const msgType = is_dupe || can_create || no_match}
-        {#if msgType}
-          {@const msg = {
+        {@const msg = msgType && {
         dupe: duplicateOptionMsg,
         create: createOptionMsg,
         'no-match': noMatchingOptionsMsg,
       }[msgType]}
+        {#if msg}
           <li
             onclick={(event) => {
               if (msgType === `create` && allowUserOptions) {
@@ -794,7 +946,7 @@ function portal(node, params) {
             ? duplicateOptionMsg
             : ``}
             class:active={option_msg_is_active}
-            onmouseover={() => (option_msg_is_active = true)}
+            onmouseover={() => !ignore_hover && (option_msg_is_active = true)}
             onfocus={() => (option_msg_is_active = true)}
             onmouseout={() => (option_msg_is_active = false)}
             onblur={() => (option_msg_is_active = false)}
@@ -819,6 +971,11 @@ function portal(node, params) {
           </li>
         {/if}
       {/if}
+      {#if loadOptions && load_options_loading}
+        <li class="loading-more" role="status" aria-label="Loading more options">
+          <CircleSpinner />
+        </li>
+      {/if}
     </ul>
   {/if}
 </div>
@@ -963,12 +1120,6 @@ function portal(node, params) {
     padding: var(--sms-options-padding);
     margin: var(--sms-options-margin, inherit);
   }
-  :is(div.multiselect.open) {
-    /* increase z-index when open to ensure the dropdown of one <MultiSelect />
-    displays above that of another slightly below it on the page */
-    /* This z-index is for the div.multiselect itself, portal has its own higher z-index */
-    z-index: var(--sms-open-z-index, 4);
-  }
   ul.options.hidden {
     visibility: hidden;
     opacity: 0;
@@ -1008,10 +1159,32 @@ function portal(node, params) {
     margin-right: 6px;
     accent-color: var(--sms-active-color, cornflowerblue);
   }
+  /* Select all option styling */
+  ul.options > li.select-all {
+    border-bottom: var(--sms-select-all-border-bottom, 1px solid lightgray);
+    font-weight: var(--sms-select-all-font-weight, 500);
+    color: var(--sms-select-all-color, inherit);
+    background: var(--sms-select-all-bg, transparent);
+    margin-bottom: var(--sms-select-all-margin-bottom, 2pt);
+  }
+  ul.options > li.select-all:hover {
+    background: var(
+      --sms-select-all-hover-bg,
+      var(--sms-li-active-bg, var(--sms-active-color, rgba(0, 0, 0, 0.15)))
+    );
+  }
   :is(span.max-select-msg) {
     padding: 0 3pt;
   }
   ::highlight(sms-search-matches) {
     color: mediumaquamarine;
   }
+  /* Loading more indicator for infinite scrolling */
+  ul.options > li.loading-more {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    padding: 8pt;
+    cursor: default;
+  }
 </style>