svelte-multiselect 11.0.0-rc.1 → 11.1.0

package/dist/MultiSelect.svelte

@@ -1,94 +1,30 @@
-<script>import { createEventDispatcher, tick } from 'svelte';
+<script lang="ts">import { browser } from '$app/environment';
+import { tick } from 'svelte';
 import { flip } from 'svelte/animate';
 import CircleSpinner from './CircleSpinner.svelte';
 import Wiggle from './Wiggle.svelte';
 import { CrossIcon, DisabledIcon, ExpandIcon } from './icons';
-import { get_label, get_style } from './utils';
-export let activeIndex = null;
-export let activeOption = null;
-export let createOptionMsg = `Create this option...`;
-export let allowUserOptions = false;
-export let allowEmpty = false; // added for https://github.com/janosh/svelte-multiselect/issues/192
-export let autocomplete = `off`;
-export let autoScroll = true;
-export let breakpoint = 800; // any screen with more horizontal pixels is considered desktop, below is mobile
-export let defaultDisabledTitle = `This option is disabled`;
-export let disabled = false;
-export let disabledInputTitle = `This input is disabled`;
-// prettier-ignore
-export let duplicateOptionMsg = `This option is already selected`;
-export let duplicates = false; // whether to allow duplicate options
-// takes two options and returns true if they are equal
-// case-insensitive equality comparison after string coercion and looks only at the `label` key of object options by default
-export let key = (opt) => `${get_label(opt)}`.toLowerCase();
-export let filterFunc = (opt, searchText) => {
+import { get_label, get_style, highlight_matching_nodes } from './utils';
+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, key = (opt) => `${get_label(opt)}`.toLowerCase(), filterFunc = (opt, searchText) => {
     if (!searchText)
         return true;
     return `${get_label(opt)}`.toLowerCase().includes(searchText.toLowerCase());
-};
-export let closeDropdownOnSelect = `desktop`;
-export let form_input = null;
-export let highlightMatches = true;
-export let id = null;
-export let input = null;
-export let inputClass = ``;
-export let inputStyle = null;
-export let inputmode = null;
-export let invalid = false;
-export let liActiveOptionClass = ``;
-export let liActiveUserMsgClass = ``;
-export let liOptionClass = ``;
-export let liOptionStyle = null;
-export let liSelectedClass = ``;
-export let liSelectedStyle = null;
-export let liUserMsgClass = ``;
-export let loading = false;
-export let matchingOptions = [];
-export let maxOptions = undefined;
-export let maxSelect = null; // null means there is no upper limit for selected.length
-export let maxSelectMsg = (current, max) => (max > 1 ? `${current}/${max}` : ``);
-export let maxSelectMsgClass = ``;
-export let name = null;
-export let noMatchingOptionsMsg = `No matching options`;
-export let open = false;
-export let options;
-export let outerDiv = null;
-export let outerDivClass = ``;
-export let parseLabelsAsHtml = false; // should not be combined with allowUserOptions!
-export let pattern = null;
-export let placeholder = null;
-export let removeAllTitle = `Remove all`;
-export let removeBtnTitle = `Remove`;
-export let minSelect = null; // null means there is no lower limit for selected.length
-export let required = false;
-export let resetFilterOnAdd = true;
-export let searchText = ``;
-export let selected = options
+}, closeDropdownOnSelect = `desktop`, 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(``), selected = $bindable(options
     ?.filter((opt) => opt instanceof Object && opt?.preselected)
-    .slice(0, maxSelect ?? undefined) ?? []; // don't allow more than maxSelect preselected options
-export let sortSelected = false;
-export let selectedOptionsDraggable = !sortSelected;
-export let style = null;
-export let ulOptionsClass = ``;
-export let ulSelectedClass = ``;
-export let ulSelectedStyle = null;
-export let ulOptionsStyle = null;
-export let value = null;
-const selected_to_value = (selected) => {
-    value = maxSelect === 1 ? selected[0] ?? null : selected;
-};
-const value_to_selected = (value) => {
+    .slice(0, maxSelect ?? undefined) ?? []), sortSelected = false, selectedOptionsDraggable = !sortSelected, style = null, ulOptionsClass = ``, ulSelectedClass = ``, ulSelectedStyle = null, ulOptionsStyle = null, value = $bindable(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();
+$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
+$effect.pre(() => {
     if (maxSelect === 1)
         selected = value ? [value] : [];
     else
         selected = value ?? [];
-};
-// 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
-$: selected_to_value(selected);
-$: value_to_selected(value);
-let wiggle = false; // controls wiggle animation when user tries to exceed maxSelect
+}); // sync value updates to selected
+let wiggle = $state(false); // controls wiggle animation when user tries to exceed maxSelect
 if (!(options?.length > 0)) {
     if (allowUserOptions || loading || disabled || allowEmpty) {
         options = []; // initializing as array avoids errors when component mounts
@@ -123,30 +59,34 @@ if (maxOptions &&
     (typeof maxOptions != `number` || maxOptions < 0 || maxOptions % 1 != 0)) {
     console.error(`MultiSelect's maxOptions must be undefined or a positive integer, got ${maxOptions}`);
 }
-const dispatch = createEventDispatcher();
-let option_msg_is_active = false; // controls active state of <li>{createOptionMsg}</li>
-let window_width;
+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
-$: matchingOptions = options.filter((opt) => filterFunc(opt, searchText) &&
-    // remove already selected options from dropdown list unless duplicate selections are allowed
-    (!selected.map(key).includes(key(opt)) || duplicates));
+$effect.pre(() => {
+    matchingOptions = options.filter((opt) => filterFunc(opt, searchText) &&
+        // remove already selected options from dropdown list unless duplicate selections are allowed
+        (!selected.map(key).includes(key(opt)) || duplicates));
+});
 // raise if matchingOptions[activeIndex] does not yield a value
 if (activeIndex !== null && !matchingOptions[activeIndex]) {
     throw `Run time error, activeIndex=${activeIndex} is out of bounds, matchingOptions.length=${matchingOptions.length}`;
 }
 // update activeOption when activeIndex changes
-$: activeOption = matchingOptions[activeIndex ?? -1] ?? null;
+$effect(() => {
+    activeOption = matchingOptions[activeIndex ?? -1] ?? null;
+});
 // add an option to selected list
-function add(option, event) {
-    if (maxSelect && maxSelect > 1 && selected.length >= maxSelect)
+function add(option_to_add, event) {
+    event.stopPropagation();
+    if (maxSelect !== null && selected.length >= maxSelect)
         wiggle = true;
-    if (!isNaN(Number(option)) && typeof selected.map(get_label)[0] === `number`) {
-        option = Number(option); // convert to number if possible
+    if (!isNaN(Number(option_to_add)) && typeof selected.map(get_label)[0] === `number`) {
+        option_to_add = Number(option_to_add); // convert to number if possible
     }
-    const is_duplicate = selected.map(key).includes(key(option));
+    const is_duplicate = selected.map(key).includes(key(option_to_add));
     if ((maxSelect === null || maxSelect === 1 || selected.length < maxSelect) &&
         (duplicates || !is_duplicate)) {
-        if (!options.includes(option) && // first check if we find option in the options list
+        if (!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) &&
@@ -155,34 +95,34 @@ function add(option, event) {
             // a new option from the user-entered text
             if (typeof options[0] === `object`) {
                 // if 1st option is an object, we create new option as object to keep type homogeneity
-                option = { label: searchText };
+                option_to_add = { label: searchText };
             }
             else {
                 if ([`number`, `undefined`].includes(typeof 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 = Number(searchText);
+                    option_to_add = Number(searchText);
                 }
                 else {
-                    option = searchText; // else create custom option as string
+                    option_to_add = searchText; // else create custom option as string
                 }
-                dispatch(`create`, { option });
+                oncreate?.({ option: option_to_add });
             }
             if (allowUserOptions === `append`)
-                options = [...options, option];
+                options = [...options, option_to_add];
         }
         if (resetFilterOnAdd)
             searchText = ``; // reset search string on selection
-        if ([``, undefined, null].includes(option)) {
-            console.error(`MultiSelect: encountered falsy option ${option}`);
+        if ([``, undefined, null].includes(option_to_add)) {
+            console.error(`MultiSelect: encountered falsy option ${option_to_add}`);
             return;
         }
         if (maxSelect === 1) {
             // for maxSelect = 1 we always replace current option with new one
-            selected = [option];
+            selected = [option_to_add];
         }
         else {
-            selected = [...selected, option];
+            selected = [...selected, option_to_add];
             if (sortSelected === true) {
                 selected = selected.sort((op1, op2) => {
                     const [label1, label2] = [get_label(op1), get_label(op2)];
@@ -196,42 +136,44 @@ function add(option, event) {
         }
         const reached_max_select = selected.length === maxSelect;
         const dropdown_should_close = closeDropdownOnSelect === true ||
-            (closeDropdownOnSelect === `desktop` && window_width < breakpoint);
+            (closeDropdownOnSelect === `desktop` && window_width && window_width < breakpoint);
         if (reached_max_select || dropdown_should_close) {
             close_dropdown(event);
         }
         else if (!dropdown_should_close) {
             input?.focus();
         }
-        dispatch(`add`, { option });
-        dispatch(`change`, { option, type: `add` });
+        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
-function remove(to_remove) {
+function remove(option_to_drop, event) {
+    event.stopPropagation();
     if (selected.length === 0)
         return;
-    const idx = selected.findIndex((opt) => key(opt) === key(to_remove));
-    let [option] = selected.splice(idx, 1); // remove option from selected list
-    if (option === undefined && allowUserOptions) {
+    const idx = selected.findIndex((opt) => key(opt) === key(option_to_drop));
+    let [option_removed] = selected.splice(idx, 1); // remove option from selected list
+    if (option_removed === undefined && allowUserOptions) {
         // 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 = (other_ops_type ? { label: to_remove } : to_remove);
+        option_removed = (other_ops_type ? { label: option_to_drop } : option_to_drop);
     }
-    if (option === undefined) {
-        return console.error(`Multiselect can't remove selected option ${JSON.stringify(to_remove)}, not found in selected list`);
+    if (option_removed === undefined) {
+        return console.error(`Multiselect can't remove selected option ${JSON.stringify(option_to_drop)}, not found in selected list`);
     }
     selected = [...selected]; // trigger Svelte rerender
     invalid = false; // reset error status whenever items are removed
     form_input?.setCustomValidity(``);
-    dispatch(`remove`, { option });
-    dispatch(`change`, { option, type: `remove` });
+    onremove?.({ option: option_removed });
+    onchange?.({ option: option_removed, type: `remove` });
 }
 function open_dropdown(event) {
+    event.stopPropagation();
     if (disabled)
         return;
     open = true;
@@ -239,45 +181,54 @@ function open_dropdown(event) {
         // avoid double-focussing input when event that opened dropdown was already input FocusEvent
         input?.focus();
     }
-    dispatch(`open`, { event });
+    onopen?.({ event });
 }
 function close_dropdown(event) {
     open = false;
     input?.blur();
     activeIndex = null;
-    dispatch(`close`, { event });
+    onclose?.({ event });
 }
 // 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
     if (event.key === `Escape` || event.key === `Tab`) {
+        event.stopPropagation();
         close_dropdown(event);
         searchText = ``;
     }
     // on enter key: toggle active option and reset search text
     else if (event.key === `Enter`) {
+        event.stopPropagation();
         event.preventDefault(); // prevent enter key from triggering form submission
         if (activeOption) {
-            selected.includes(activeOption) ? remove(activeOption) : add(activeOption, event);
+            if (selected.includes(activeOption))
+                remove(activeOption, event);
+            else
+                add(activeOption, event);
             searchText = ``;
         }
         else if (allowUserOptions && searchText.length > 0) {
             // user entered text but no options match, so if allowUserOptions is truthy, we create new option
             add(searchText, event);
         }
-        // no active option and no search text means the options dropdown is closed
-        // in which case enter means open it
-        else
+        else {
+            // no active option and no search text means the options dropdown is closed
+            // in which case enter means open it
             open_dropdown(event);
+        }
     }
     // on up/down arrow keys: update active option
     else if ([`ArrowDown`, `ArrowUp`].includes(event.key)) {
+        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;
@@ -287,7 +238,7 @@ async function handle_keydown(event) {
             // if no option is active and no options are matching, do nothing
             return;
         }
-        event.preventDefault();
+        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;
@@ -305,24 +256,28 @@ async function handle_keydown(event) {
     }
     // on backspace key: remove last selected option
     else if (event.key === `Backspace` && selected.length > 0 && !searchText) {
-        remove(selected.at(-1));
+        event.stopPropagation();
+        // Don't prevent default, allow normal backspace behavior if not removing
+        remove(selected.at(-1), event);
     }
     // make first matching option active on any keypress (if none of the above special cases match)
-    else if (matchingOptions.length > 0) {
+    else if (matchingOptions.length > 0 && activeIndex === null) {
+        // Don't stop propagation or prevent default here, allow normal character input
         activeIndex = 0;
     }
 }
-function remove_all() {
-    dispatch(`removeAll`, { options: selected });
-    dispatch(`change`, { options: selected, type: `removeAll` });
+function remove_all(event) {
+    event.stopPropagation();
+    onremoveAll?.({ options: selected });
+    onchange?.({ options: selected, type: `removeAll` });
     selected = [];
     searchText = ``;
 }
-$: is_selected = (label) => selected.map(get_label).includes(label);
+let is_selected = $derived((label) => selected.map(get_label).includes(label));
 const if_enter_or_space = (handler) => (event) => {
     if ([`Enter`, `Space`].includes(event.code)) {
         event.preventDefault();
-        handler();
+        handler(event);
     }
 };
 function on_click_outside(event) {
@@ -330,7 +285,7 @@ function on_click_outside(event) {
         close_dropdown(event);
     }
 }
-let drag_idx = null;
+let drag_idx = $state(null);
 // event handlers enable dragging to reorder selected options
 const drop = (target_idx) => (event) => {
     if (!event.dataTransfer)
@@ -357,62 +312,83 @@ const dragstart = (idx) => (event) => {
     event.dataTransfer.dropEffect = `move`;
     event.dataTransfer.setData(`text/plain`, `${idx}`);
 };
-let ul_options;
+let ul_options = $state();
 // highlight text matching user-entered search text in available options
 function highlight_matching_options(event) {
-    if (!highlightMatches || typeof CSS == `undefined` || !CSS.highlights)
-        return; // abort if CSS highlight API not supported
-    // clear previous ranges from HighlightRegistry
-    CSS.highlights.clear();
+    if (!highlightMatches || !ul_options)
+        return;
     // get input's search query
     const query = event?.target?.value.trim().toLowerCase();
     if (!query)
         return;
-    const tree_walker = document.createTreeWalker(ul_options, NodeFilter.SHOW_TEXT, {
-        acceptNode: (node) => {
-            // don't highlight text in the "no matching options" message
-            if (node?.textContent === noMatchingOptionsMsg)
-                return NodeFilter.FILTER_REJECT;
-            return NodeFilter.FILTER_ACCEPT;
-        },
-    });
-    const text_nodes = [];
-    let current_node = tree_walker.nextNode();
-    while (current_node) {
-        text_nodes.push(current_node);
-        current_node = tree_walker.nextNode();
-    }
-    // iterate over all text nodes and find matches
-    const ranges = text_nodes.map((el) => {
-        const text = el.textContent?.toLowerCase();
-        const indices = [];
-        let start_pos = 0;
-        while (text && start_pos < text.length) {
-            const index = text.indexOf(query, start_pos);
-            if (index === -1)
-                break;
-            indices.push(index);
-            start_pos = index + query.length;
-        }
-        // create range object for each str found in the text node
-        return indices.map((index) => {
-            const range = new Range();
-            range.setStart(el, index);
-            range.setEnd(el, index + query.length);
-            return range;
-        });
-    });
-    // create Highlight object from ranges and add to registry
-    CSS.highlights.set(`sms-search-matches`, new Highlight(...ranges.flat()));
+    highlight_matching_nodes(ul_options, query, noMatchingOptionsMsg);
 }
+const handle_input_keydown = (event) => {
+    handle_keydown(event); // Restore internal logic
+    // Call original forwarded handler
+    onkeydown?.(event);
+};
+const handle_input_focus = (event) => {
+    open_dropdown(event); // Internal logic
+    // Call original forwarded handler
+    onfocus?.(event);
+};
 // reset form validation when required prop changes
 // https://github.com/janosh/svelte-multiselect/issues/285
-$: required, form_input?.setCustomValidity(``);
+$effect.pre(() => {
+    required = required; // trigger effect when required changes
+    form_input?.setCustomValidity(``);
+});
+function portal(node, params) {
+    let { target_node, active } = params;
+    if (!active)
+        return;
+    let render_in_place = !browser || !document.body.contains(node);
+    if (!render_in_place) {
+        document.body.appendChild(node);
+        node.style.position = `fixed`;
+        const update_position = () => {
+            if (!target_node || !open)
+                return (node.hidden = true);
+            const rect = target_node.getBoundingClientRect();
+            node.style.left = `${rect.left}px`;
+            node.style.top = `${rect.bottom}px`;
+            node.style.width = `${rect.width}px`;
+            node.hidden = false;
+        };
+        if (open)
+            tick().then(update_position);
+        window.addEventListener(`scroll`, update_position, true);
+        window.addEventListener(`resize`, update_position);
+        $effect.pre(() => {
+            if (open && target_node)
+                update_position();
+            else
+                node.hidden = true;
+        });
+        return {
+            update(params) {
+                target_node = params.target_node;
+                render_in_place = !browser || !document.body.contains(node);
+                if (open && !render_in_place && target_node)
+                    tick().then(update_position);
+                else if (!open || !target_node)
+                    node.hidden = true;
+            },
+            destroy() {
+                if (!render_in_place)
+                    node.remove();
+                window.removeEventListener(`scroll`, update_position, true);
+                window.removeEventListener(`resize`, update_position);
+            },
+        };
+    }
+}
 </script>
 
 <svelte:window
-  on:click={on_click_outside}
-  on:touchstart={on_click_outside}
+  onclick={on_click_outside}
+  ontouchstart={on_click_outside}
   bind:innerWidth={window_width}
 />
 
@@ -422,8 +398,8 @@ $: required, form_input?.setCustomValidity(``);
   class:single={maxSelect === 1}
   class:open
   class:invalid
-  class="multiselect {outerDivClass}"
-  on:mouseup|stopPropagation={open_dropdown}
+  class="multiselect {outerDivClass} {rest.class ?? ``}"
+  onmouseup={open_dropdown}
   title={disabled ? disabledInputTitle : null}
   data-id={id}
   role="searchbox"
@@ -434,14 +410,14 @@ $: required, form_input?.setCustomValidity(``);
   <!-- bind:value={selected} prevents form submission if required prop is true and no options are selected -->
   <input
     {name}
-    {required}
+    required={Boolean(required)}
     value={selected.length >= Number(required) ? JSON.stringify(selected) : null}
     tabindex="-1"
     aria-hidden="true"
     aria-label="ignore this, used only to prevent form submission if select is required but empty"
     class="form-control"
     bind:this={form_input}
-    on:invalid={() => {
+    oninvalid={() => {
       invalid = true
       let msg
       if (maxSelect && maxSelect > 1 && Number(required) > 1) {
@@ -454,49 +430,63 @@ $: required, form_input?.setCustomValidity(``);
       form_input?.setCustomValidity(msg)
     }}
   />
-  <slot name="expand-icon" {open}>
+  {#if expandIcon}
+    {@render expandIcon({ open })}
+  {:else}
     <ExpandIcon width="15px" style="min-width: 1em; padding: 0 1pt; cursor: pointer;" />
-  </slot>
+  {/if}
   <ul
     class="selected {ulSelectedClass}"
     aria-label="selected options"
     style={ulSelectedStyle}
   >
     {#each selected as option, idx (duplicates ? [key(option), idx] : key(option))}
+      {@const selectedOptionStyle =
+        [get_style(option, `selected`), liSelectedStyle].filter(Boolean).join(` `) ||
+        null}
       <li
         class={liSelectedClass}
         role="option"
         aria-selected="true"
         animate:flip={{ duration: 100 }}
         draggable={selectedOptionsDraggable && !disabled && selected.length > 1}
-        on:dragstart={dragstart(idx)}
-        on:drop|preventDefault={drop(idx)}
-        on:dragenter={() => (drag_idx = idx)}
-        on:dragover|preventDefault
+        ondragstart={dragstart(idx)}
+        ondragover={(event) => {
+          event.preventDefault() // needed for ondrop to fire
+        }}
+        ondrop={drop(idx)}
+        ondragenter={() => (drag_idx = idx)}
         class:active={drag_idx === idx}
-        style="{get_style(option, `selected`)} {liSelectedStyle}"
+        style={selectedOptionStyle}
       >
-        <!-- on:dragover|preventDefault needed for the drop to succeed https://stackoverflow.com/a/31085796 -->
-        <slot name="selected" {option} {idx}>
-          <slot {option} {idx}>
-            {#if parseLabelsAsHtml}
-              {@html get_label(option)}
-            {:else}
-              {get_label(option)}
-            {/if}
-          </slot>
-        </slot>
+        {#if selectedItem}
+          {@render selectedItem({
+            option,
+            idx,
+          })}
+        {:else if children}
+          {@render children({
+            option,
+            idx,
+          })}
+        {:else if parseLabelsAsHtml}
+          {@html get_label(option)}
+        {:else}
+          {get_label(option)}
+        {/if}
         {#if !disabled && (minSelect === null || selected.length > minSelect)}
           <button
-            on:mouseup|stopPropagation={() => remove(option)}
-            on:keydown={if_enter_or_space(() => remove(option))}
+            onclick={(event) => remove(option, event)}
+            onkeydown={if_enter_or_space((event) => remove(option, event))}
             type="button"
             title="{removeBtnTitle} {get_label(option)}"
             class="remove"
           >
-            <slot name="remove-icon">
+            {#if removeIcon}
+              {@render removeIcon()}
+            {:else}
               <CrossIcon width="15px" />
-            </slot>
+            {/if}
           </button>
         {/if}
       </li>
@@ -506,11 +496,6 @@ $: required, form_input?.setCustomValidity(``);
       style={inputStyle}
       bind:this={input}
       bind:value={searchText}
-      on:mouseup|self|stopPropagation={open_dropdown}
-      on:keydown|stopPropagation={handle_keydown}
-      on:focus
-      on:focus={open_dropdown}
-      on:input={highlight_matching_options}
       {id}
       {disabled}
       {autocomplete}
@@ -518,41 +503,47 @@ $: required, form_input?.setCustomValidity(``);
       {pattern}
       placeholder={selected.length == 0 ? placeholder : null}
       aria-invalid={invalid ? `true` : null}
-      on:drop={() => false}
-      on:blur
-      on:change
-      on:click
-      on:keydown
-      on:keyup
-      on:mousedown
-      on:mouseenter
-      on:mouseleave
-      on:touchcancel
-      on:touchend
-      on:touchmove
-      on:touchstart
+      ondrop={() => false}
+      onmouseup={open_dropdown}
+      onkeydown={handle_input_keydown}
+      onfocus={handle_input_focus}
+      oninput={highlight_matching_options}
+      {onblur}
+      {onclick}
+      {onkeyup}
+      {onmousedown}
+      {onmouseenter}
+      {onmouseleave}
+      {ontouchcancel}
+      {ontouchend}
+      {ontouchmove}
+      {ontouchstart}
+      {...rest}
     />
     <!-- the above on:* lines forward potentially useful DOM events -->
-    <slot
-      name="after-input"
-      {selected}
-      {disabled}
-      {invalid}
-      {id}
-      {placeholder}
-      {open}
-      {required}
-    />
+    {@render afterInput?.({
+      selected,
+      disabled,
+      invalid,
+      id,
+      placeholder,
+      open,
+      required,
+    })}
   </ul>
   {#if loading}
-    <slot name="spinner">
+    {#if spinner}
+      {@render spinner()}
+    {:else}
       <CircleSpinner />
-    </slot>
+    {/if}
   {/if}
   {#if disabled}
-    <slot name="disabled-icon">
+    {#if disabledIcon}
+      {@render disabledIcon()}
+    {:else}
       <DisabledIcon width="14pt" style="margin: 0 2pt;" data-name="disabled-icon" />
-    </slot>
+    {/if}
   {:else if selected.length > 0}
     {#if maxSelect && (maxSelect > 1 || maxSelectMsg)}
       <Wiggle bind:wiggle angle={20}>
@@ -566,12 +557,14 @@ $: required, form_input?.setCustomValidity(``);
         type="button"
         class="remove remove-all"
         title={removeAllTitle}
-        on:mouseup|stopPropagation={remove_all}
-        on:keydown={if_enter_or_space(remove_all)}
+        onclick={remove_all}
+        onkeydown={if_enter_or_space(remove_all)}
       >
-        <slot name="remove-icon">
+        {#if removeIcon}
+          {@render removeIcon()}
+        {:else}
           <CrossIcon width="15px" />
-        </slot>
+        {/if}
       </button>
     {/if}
   {/if}
@@ -579,6 +572,7 @@ $: required, form_input?.setCustomValidity(``);
   <!-- only render options dropdown if options or searchText is not empty (needed to avoid briefly flashing empty dropdown) -->
   {#if (searchText && noMatchingOptionsMsg) || options?.length > 0}
     <ul
+      use:portal={{ target_node: outerDiv, ...portal_params }}
       class:hidden={!open}
       class="options {ulOptionsClass}"
       role="listbox"
@@ -588,19 +582,21 @@ $: required, form_input?.setCustomValidity(``);
       bind:this={ul_options}
       style={ulOptionsStyle}
     >
-      {#each matchingOptions.slice(0, Math.max(0, maxOptions ?? 0) || Infinity) as option, idx}
+      {#each matchingOptions.slice(0, Math.max(0, maxOptions ?? 0) || Infinity) as optionItem, idx (duplicates ? [key(optionItem), idx] : key(optionItem))}
         {@const {
           label,
           disabled = null,
           title = null,
           selectedTitle = null,
           disabledTitle = defaultDisabledTitle,
-        } = option instanceof Object ? option : { label: option }}
+        } = optionItem instanceof Object ? optionItem : { label: optionItem }}
         {@const active = activeIndex === idx}
+        {@const optionStyle =
+          [get_style(optionItem, `option`), liOptionStyle].filter(Boolean).join(` `) ||
+          null}
         <li
-          on:mousedown|stopPropagation
-          on:mouseup|stopPropagation={(event) => {
-            if (!disabled) add(option, event)
+          onclick={(event) => {
+            if (!disabled) add(optionItem, event)
           }}
           title={disabled
             ? disabledTitle
@@ -609,27 +605,37 @@ $: required, form_input?.setCustomValidity(``);
           class:active
           class:disabled
           class="{liOptionClass} {active ? liActiveOptionClass : ``}"
-          on:mouseover={() => {
+          onmouseover={() => {
             if (!disabled) activeIndex = idx
           }}
-          on:focus={() => {
+          onfocus={() => {
             if (!disabled) activeIndex = idx
           }}
-          on:mouseout={() => (activeIndex = null)}
-          on:blur={() => (activeIndex = null)}
           role="option"
           aria-selected="false"
-          style="{get_style(option, `option`)} {liOptionStyle}"
+          style={optionStyle}
+          onkeydown={(event) => {
+            if (!disabled && (event.key === `Enter` || event.code === `Space`)) {
+              event.preventDefault()
+              add(optionItem, event)
+            }
+          }}
         >
-          <slot name="option" {option} {idx}>
-            <slot {option} {idx}>
-              {#if parseLabelsAsHtml}
-                {@html get_label(option)}
-              {:else}
-                {get_label(option)}
-              {/if}
-            </slot>
-          </slot>
+          {#if option}
+            {@render option({
+              option: optionItem,
+              idx,
+            })}
+          {:else if children}
+            {@render children({
+              option: optionItem,
+              idx,
+            })}
+          {:else if parseLabelsAsHtml}
+            {@html get_label(optionItem)}
+          {:else}
+            {get_label(optionItem)}
+          {/if}
         </li>
       {/each}
       {#if searchText}
@@ -646,16 +652,31 @@ $: required, form_input?.setCustomValidity(``);
             'no-match': noMatchingOptionsMsg,
           }[msgType]}
           <li
-            on:mousedown|stopPropagation
-            on:mouseup|stopPropagation={(event) => {
-              if (allowUserOptions) add(searchText, event)
+            onclick={(event) => {
+              if (msgType === `create` && allowUserOptions) {
+                add(searchText as Option, event)
+              }
             }}
-            title={createOptionMsg}
+            onkeydown={(event) => {
+              if (
+                msgType === `create` &&
+                allowUserOptions &&
+                (event.key === `Enter` || event.code === `Space`)
+              ) {
+                event.preventDefault()
+                add(searchText as Option, event)
+              }
+            }}
+            title={msgType === `create`
+              ? createOptionMsg
+              : msgType === `dupe`
+                ? duplicateOptionMsg
+                : ``}
             class:active={option_msg_is_active}
-            on:mouseover={() => (option_msg_is_active = true)}
-            on:focus={() => (option_msg_is_active = true)}
-            on:mouseout={() => (option_msg_is_active = false)}
-            on:blur={() => (option_msg_is_active = false)}
+            onmouseover={() => (option_msg_is_active = true)}
+            onfocus={() => (option_msg_is_active = true)}
+            onmouseout={() => (option_msg_is_active = false)}
+            onblur={() => (option_msg_is_active = false)}
             role="option"
             aria-selected="false"
             class="user-msg {liUserMsgClass} {option_msg_is_active
@@ -667,9 +688,11 @@ $: required, form_input?.setCustomValidity(``);
               'no-match': `default`,
             }[msgType]}
           >
-            <slot name="user-msg" {searchText} {msgType} {msg}>
+            {#if userMsg}
+              {@render userMsg({ searchText, msgType, msg })}
+            {:else}
               {msg}
-            </slot>
+            {/if}
           </li>
         {/if}
       {/if}
@@ -678,7 +701,7 @@ $: required, form_input?.setCustomValidity(``);
 </div>
 
 <style>
-  :where(div.multiselect) {
+  :is(div.multiselect) {
     position: relative;
     align-items: center;
     display: flex;
@@ -695,27 +718,27 @@ $: required, form_input?.setCustomValidity(``);
     min-height: var(--sms-min-height, 22pt);
     margin: var(--sms-margin);
   }
-  :where(div.multiselect.open) {
+  :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 */
     z-index: var(--sms-open-z-index, 4);
   }
-  :where(div.multiselect:focus-within) {
+  :is(div.multiselect:focus-within) {
     border: var(--sms-focus-border, 1pt solid var(--sms-active-color, cornflowerblue));
   }
-  :where(div.multiselect.disabled) {
+  :is(div.multiselect.disabled) {
     background: var(--sms-disabled-bg, lightgray);
     cursor: not-allowed;
   }
 
-  :where(div.multiselect > ul.selected) {
+  :is(div.multiselect > ul.selected) {
     display: flex;
     flex: 1;
     padding: 0;
     margin: 0;
     flex-wrap: wrap;
   }
-  :where(div.multiselect > ul.selected > li) {
+  :is(div.multiselect > ul.selected > li) {
     align-items: center;
     border-radius: 3pt;
     display: flex;
@@ -727,13 +750,13 @@ $: required, form_input?.setCustomValidity(``);
     padding: var(--sms-selected-li-padding, 1pt 5pt);
     color: var(--sms-selected-text-color, var(--sms-text-color));
   }
-  :where(div.multiselect > ul.selected > li[draggable='true']) {
+  :is(div.multiselect > ul.selected > li[draggable='true']) {
     cursor: grab;
   }
-  :where(div.multiselect > ul.selected > li.active) {
+  :is(div.multiselect > ul.selected > li.active) {
     background: var(--sms-li-active-bg, var(--sms-active-color, rgba(0, 0, 0, 0.15)));
   }
-  :where(div.multiselect button) {
+  :is(div.multiselect button) {
     border-radius: 50%;
     display: flex;
     transition: 0.2s;
@@ -742,22 +765,22 @@ $: required, form_input?.setCustomValidity(``);
     border: none;
     cursor: pointer;
     outline: none;
-    padding: 0;
+    padding: 1pt;
     margin: 0 0 0 3pt; /* CSS reset */
   }
-  :where(div.multiselect button.remove-all) {
+  :is(div.multiselect button.remove-all) {
     margin: 0 3pt;
   }
-  :where(ul.selected > li button:hover, button.remove-all:hover, button:focus) {
+  :is(ul.selected > li button:hover, button.remove-all:hover, button:focus) {
     color: var(--sms-remove-btn-hover-color, lightskyblue);
     background: var(--sms-remove-btn-hover-bg, rgba(0, 0, 0, 0.2));
   }
 
-  :where(div.multiselect input) {
+  :is(div.multiselect input) {
     margin: auto 0; /* CSS reset */
     padding: 0; /* CSS reset */
   }
-  :where(div.multiselect > ul.selected > input) {
+  :is(div.multiselect > ul.selected > input) {
     border: none;
     outline: none;
     background: none;
@@ -769,13 +792,13 @@ $: required, form_input?.setCustomValidity(``);
     cursor: inherit; /* needed for disabled state */
     border-radius: 0; /* reset ul.selected > li */
   }
-  /* don't wrap ::placeholder rules in :where() as it seems to be overpowered by browser defaults i.t.o. specificity */
+  /* don't wrap ::placeholder rules in :is() as it seems to be overpowered by browser defaults i.t.o. specificity */
   div.multiselect > ul.selected > input::placeholder {
     padding-left: 5pt;
     color: var(--sms-placeholder-color);
     opacity: var(--sms-placeholder-opacity);
   }
-  :where(div.multiselect > input.form-control) {
+  :is(div.multiselect > input.form-control) {
     width: 2em;
     position: absolute;
     background: transparent;
@@ -786,14 +809,19 @@ $: required, form_input?.setCustomValidity(``);
     pointer-events: none;
   }
 
-  :where(div.multiselect > ul.options) {
+  ul.options {
     list-style: none;
+    /* top, left, width, position are managed by portal when active */
+    /* but provide defaults for non-portaled or initial state */
+    position: absolute; /* Default, overridden by portal to fixed when open */
     top: 100%;
     left: 0;
     width: 100%;
-    position: absolute;
+    /* Default z-index if not portaled/overridden by portal */
+    z-index: var(--sms-options-z-index, 3);
+
     overflow: auto;
-    transition: all 0.2s;
+    transition: all 0.2s; /* Consider if this transition is desirable with portal positioning */
     box-sizing: border-box;
     background: var(--sms-options-bg, white);
     max-height: var(--sms-options-max-height, 50vh);
@@ -805,35 +833,41 @@ $: required, form_input?.setCustomValidity(``);
     padding: var(--sms-options-padding);
     margin: var(--sms-options-margin, inherit);
   }
-  :where(div.multiselect > ul.options.hidden) {
+  :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;
     transform: translateY(50px);
   }
-  :where(div.multiselect > ul.options > li) {
+  ul.options > li {
     padding: 3pt 2ex;
     cursor: pointer;
     scroll-margin: var(--sms-options-scroll-margin, 100px);
   }
-  :where(div.multiselect > ul.options .user-msg) {
+  ul.options .user-msg {
     /* block needed so vertical padding applies to span */
     display: block;
     padding: 3pt 2ex;
   }
-  :where(div.multiselect > ul.options > li.selected) {
+  ul.options > li.selected {
     background: var(--sms-li-selected-bg);
     color: var(--sms-li-selected-color);
   }
-  :where(div.multiselect > ul.options > li.active) {
+  ul.options > li.active {
     background: var(--sms-li-active-bg, var(--sms-active-color, rgba(0, 0, 0, 0.15)));
   }
-  :where(div.multiselect > ul.options > li.disabled) {
+  ul.options > li.disabled {
     cursor: not-allowed;
     background: var(--sms-li-disabled-bg, #f5f5f6);
     color: var(--sms-li-disabled-text, #b8b8b8);
   }
 
-  :where(span.max-select-msg) {
+  :is(span.max-select-msg) {
     padding: 0 3pt;
   }
   ::highlight(sms-search-matches) {