svelte-multiselect 8.0.4 → 8.1.0

package/MultiSelect.svelte

@@ -22,6 +22,7 @@ export let filterFunc = (op, searchText) => {
     return `${get_label(op)}`.toLowerCase().includes(searchText.toLowerCase());
 };
 export let focusInputOnSelect = `desktop`;
+export let form_input;
 export let id = null;
 export let input = null;
 export let inputClass = ``;
@@ -32,8 +33,9 @@ export let liOptionClass = ``;
 export let liSelectedClass = ``;
 export let loading = false;
 export let matchingOptions = [];
-export let maxSelect = null; // null means any number of options are selectable
+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;
@@ -45,6 +47,7 @@ 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 = ``;
@@ -76,10 +79,13 @@ if (parseLabelsAsHtml && allowUserOptions) {
     console.warn(`Don't combine parseLabelsAsHtml and allowUserOptions. It's susceptible to XSS attacks!`);
 }
 if (maxSelect !== null && maxSelect < 1) {
-    console.error(`maxSelect must be null or positive integer, got ${maxSelect}`);
+    console.error(`MultiSelect's 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}`);
+    console.error(`MultiSelect's 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`);
 }
 const dispatch = createEventDispatcher();
 let add_option_msg_is_active = false; // controls active state of <li>{addOptionMsg}</li>
@@ -161,6 +167,7 @@ function add(label, event) {
         dispatch(`add`, { option });
         dispatch(`change`, { option, type: `add` });
         invalid = false; // reset error status whenever new items are selected
+        form_input?.setCustomValidity(``);
     }
 }
 // remove an option from selected list
@@ -180,6 +187,7 @@ function remove(label) {
     dispatch(`remove`, { option });
     dispatch(`change`, { option, type: `remove` });
     invalid = false; // reset error status whenever items are removed
+    form_input?.setCustomValidity(``);
 }
 function open_dropdown(event) {
     if (disabled)
@@ -296,17 +304,30 @@ function on_click_outside(event) {
   on:mouseup|stopPropagation={open_dropdown}
   title={disabled ? disabledInputTitle : null}
   aria-disabled={disabled ? `true` : null}
+  data-id={id}
 >
   <!-- bind:value={selected} prevents form submission if required prop is true and no options are selected -->
   <input
-    {required}
     {name}
-    value={selected.length > 0 ? JSON.stringify(selected) : null}
+    required={Boolean(required)}
+    value={selected.length >= 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"
-    on:invalid={() => (invalid = true)}
+    bind:this={form_input}
+    on:invalid={() => {
+      invalid = true
+      let msg
+      if (maxSelect && maxSelect > 1 && required > 1) {
+        msg = `Please select between ${required} and ${maxSelect} options`
+      } else if (required > 1) {
+        msg = `Please select at least ${required} options`
+      } else {
+        msg = `Please select an option`
+      }
+      form_input.setCustomValidity(msg)
+    }}
   />
   <ExpandIcon width="15px" style="min-width: 1em; padding: 0 1pt;" />
   <ul class="selected {ulSelectedClass}">
@@ -319,7 +340,7 @@ function on_click_outside(event) {
             {get_label(option)}
           {/if}
         </slot>
-        {#if !disabled}
+        {#if !disabled && (minSelect === null || selected.length > minSelect)}
           <button
             on:mouseup|stopPropagation={() => remove(get_label(option))}
             on:keydown={if_enter_or_space(() => remove(get_label(option)))}
@@ -377,7 +398,7 @@ function on_click_outside(event) {
   {:else if selected.length > 0}
     {#if maxSelect && (maxSelect > 1 || maxSelectMsg)}
       <Wiggle bind:wiggle angle={20}>
-        <span style="padding: 0 3pt;">
+        <span class="max-select-msg {maxSelectMsgClass}">
           {maxSelectMsg?.(selected.length, maxSelect)}
         </span>
       </Wiggle>
@@ -607,4 +628,8 @@ function on_click_outside(event) {
     background: var(--sms-li-disabled-bg, #f5f5f6);
     color: var(--sms-li-disabled-text, #b8b8b8);
   }
+
+  :where(span.max-select-msg) {
+    padding: 0 3pt;
+  }
 </style>

package/MultiSelect.svelte.d.ts

@@ -17,6 +17,7 @@ declare const __propDef: {
         duplicates?: boolean | undefined;
         filterFunc?: ((op: Option, searchText: string) => boolean) | undefined;
         focusInputOnSelect?: boolean | "desktop" | undefined;
+        form_input: HTMLInputElement;
         id?: string | null | undefined;
         input?: HTMLInputElement | null | undefined;
         inputClass?: string | undefined;
@@ -29,6 +30,7 @@ declare const __propDef: {
         matchingOptions?: Option[] | undefined;
         maxSelect?: number | null | undefined;
         maxSelectMsg?: ((current: number, max: number) => string) | null | undefined;
+        maxSelectMsgClass?: string | undefined;
         name?: string | null | undefined;
         noMatchingOptionsMsg?: string | undefined;
         open?: boolean | undefined;
@@ -40,7 +42,8 @@ declare const __propDef: {
         placeholder?: string | null | undefined;
         removeAllTitle?: string | undefined;
         removeBtnTitle?: string | undefined;
-        required?: boolean | undefined;
+        minSelect?: number | null | undefined;
+        required?: number | boolean | undefined;
         resetFilterOnAdd?: boolean | undefined;
         searchText?: string | undefined;
         selected?: Option[] | undefined;

package/package.json

@@ -5,7 +5,7 @@
   "homepage": "https://svelte-multiselect.netlify.app",
   "repository": "https://github.com/janosh/svelte-multiselect",
   "license": "MIT",
-  "version": "8.0.4",
+  "version": "8.1.0",
   "type": "module",
   "svelte": "index.js",
   "main": "index.js",

package/readme.md

@@ -168,6 +168,12 @@ Full list of props/bindable variables for this component. The `Option` type you
 
    One of `true`, `false` or `'desktop'`. Whether to set the cursor back to the input element after selecting an element. 'desktop' means only do so if current window width is larger than the current value of `breakpoint` prop (default 800).
 
+1. ```ts
+   form_input: HTMLInputElement
+   ```
+
+   Handle to the `<input>` DOM node that's responsible for form validity checks and passing selected options to form submission handlers. Only available after component mounts (`null` before then).
+
 1. ```ts
    id: string | null = null
    ```
@@ -190,7 +196,7 @@ Full list of props/bindable variables for this component. The `Option` type you
    invalid: boolean = false
    ```
 
-   If `required=true` and user tries to submit but `selected = []` is empty, `invalid` is automatically set to `true` and CSS class `invalid` applied to the top-level `div.multiselect`. `invalid` class is removed again as soon as the user selects an option. `invalid` can also be controlled externally by binding to it `<MultiSelect bind:invalid />` and setting it to `true` based on outside events or custom validation.
+   If `required = true, 1, 2, ...` and user tries to submit form but `selected = []` is empty/`selected.length < required`, `invalid` is automatically set to `true` and CSS class `invalid` applied to the top-level `div.multiselect`. `invalid` class is removed as soon as any change to `selected` is registered. `invalid` can also be controlled externally by binding to it `<MultiSelect bind:invalid />` and setting it to `true` based on outside events or custom validation.
 
 1. ```ts
    loading: boolean = false
@@ -223,6 +229,16 @@ Full list of props/bindable variables for this component. The `Option` type you
    maxSelectMsg = (current: number, max: number) => `${current}/${max}`
    ```
 
+   Use CSS selector `span.max-select-msg` (or prop `maxSelectMsgClass` if you're using a CSS framework like Tailwind) to customize appearance of the message container.
+
+1. ```ts
+   minSelect: number | null = null
+   ```
+
+   Conditionally render the `x` button which removes a selected option depending on the number of selected options. Meaning all remove buttons disappear if `selected.length <= minSelect`. E.g. if 2 options are selected and `minSelect={3}`, users will not be able to remove any selections until they selected more than 3 options.
+
+   Note: Prop `required={3}` should be used instead if you only care about the component state at form submission time. `minSelect={3}` should be used if you want to place constraints on component state at all times.
+
 1. ```ts
    name: string | null = null
    ```
@@ -284,10 +300,10 @@ Full list of props/bindable variables for this component. The `Option` type you
    Title text to display when user hovers over button to remove selected option (which defaults to a cross icon).
 
 1. ```ts
-   required: boolean = false
+   required: boolean | number = false
    ```
 
-   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.
+   If `required = true, 1, 2, ...` forms can't be submitted without selecting given number of options. `true` means 1. `false` means even empty MultiSelect will pass form validity check. If user tries to submit a form containing MultiSelect with less than the required number of options, submission is aborted, MultiSelect scrolls into view and shows message "Please select at least `required` options".
 
 1. ```ts
    resetFilterOnAdd: boolean = true
@@ -514,6 +530,7 @@ The second method allows you to pass in custom classes to the important DOM elem
 - `ulOptionsClass`: available options listed in the dropdown when component is in `open` state
 - `liOptionClass`: list items selectable from dropdown list
 - `liActiveOptionClass`: the currently active dropdown list item (i.e. hovered or navigated to with arrow keys)
+- `maxSelectMsgClass`: small span towards the right end of the input field displaying to the user how many of the allowed number of options they've already selected
 
 This simplified version of the DOM structure of the component shows where these classes are inserted:
 
@@ -524,6 +541,7 @@ This simplified version of the DOM structure of the component shows where these
     <li class={liSelectedClass}>Selected 1</li>
     <li class={liSelectedClass}>Selected 2</li>
   </ul>
+  <span class="maxSelectMsgClass">2/5 selected</span>
   <ul class="options {ulOptionsClass}">
     <li class={liOptionClass}>Option 1</li>
     <li class="{liOptionClass} {liActiveOptionClass}">
@@ -585,7 +603,7 @@ Odd as it may seem, you get the most fine-grained control over the styling of ev
 
 ## Want to contribute?
 
-To submit a PR, clone the repo, install dependencies and start the dev server to try out your changes.
+To submit a PR, clone the repo, install dependencies and start the dev server to see changes as you make them.
 
 ```sh
 git clone https://github.com/janosh/svelte-multiselect
@@ -593,3 +611,9 @@ cd svelte-multiselect
 pnpm install
 pnpm dev
 ```
+
+To make sure your changes didn't break anything, you can run the full test suite (which also runs in CI) using:
+
+```sh
+pnpm test
+```