@xsolla/xui-multi-select 0.216.1 → 0.217.0

package/README.md

@@ -50,7 +50,7 @@ A dropdown input that allows selecting multiple values simultaneously. Displays
 - When State=Error, the error message must be linked via aria-describedby and in an aria-live=*"polite"* region.
 - The ContextMenu dropdown uses role=*"listbox"* (or role=*"menu"*) with each option as role=*"option"* / role=*"menuitemcheckbox"* and aria-checked=*"true"* / *"false"*.
 - Keyboard navigation: Enter / Space / ↓ opens the dropdown; ↑ / ↓ navigate options; Space toggles the focused option; Escape closes without further changes; Tab closes and moves focus forward.
-- When a value is added or removed (via chip ✕ or from dropdown), announce the change via aria-live=*"polite"*: *"Design added"* or *"Design removed"*.
+- When a value is added or removed (via chip ✕ or from dropdown), announce the change via aria-live=*"polite"*: *"Design added"* or *"Design removed"*.
 <!-- END:xui-mcp-instructions:multi-select -->
 
 ## Installation
@@ -158,12 +158,15 @@ Add backdrop, click-outside, and Escape handling in your layout as needed (see S
 | `errorMessage`      | `string`                                                  | —          | Error message; also marks the control invalid.                                                                                                             |
 | `variant`           | `'tag' \| 'text'`                                         | `'tag'`    | How selected options are displayed.                                                                                                                        |
 | `flexible`          | `boolean`                                                 | `true`     | When `true` the control grows with content; otherwise fixed-height.                                                                                        |
-| `removeTagsButtons` | `boolean`                                                 | `true`     | Show a remove button on each tag.                                                                                                                          |
-| `extraClear`        | `boolean`                                                 | `false`    | Show a clear-all button.                                                                                                                                   |
+| `removeTagsButtons` | `boolean`                                                 | `true`     | Show a remove button on each tag. Component-wide default — override per option with `MultiSelectOption.removable`.                                         |
+| `extraClear`        | `boolean`                                                 | `false`    | Show a clear-all button. Options with `removable: false` are kept.                                                                                         |
 | `maxHeight`         | `number`                                                  | `300`      | Maximum dropdown height in pixels.                                                                                                                         |
 | `searchable`        | `boolean`                                                 | `false`    | Show a search input at the top of the built-in dropdown that filters options in memory by label. Web only.                                                 |
 | `searchPlaceholder` | `string`                                                  | `'Search'` | Placeholder for the search input (used when `searchable`).                                                                                                 |
 | `noOptionsMessage`  | `string`                                                  | `'No results'` | Message shown when the search filter matches no options.                                                                                               |
+| `selectAll`         | `boolean`                                                 | `false`    | Show a select-all / deselect-all row at the top of the built-in dropdown. Scoped to the options currently listed; skips `disabled`; never deselects locked options. Ignored when `dropdownMenu` is `false`. |
+| `selectAllLabel`    | `string`                                                  | `'Select all'` | Label of the select-all row (used when `selectAll`).                                                                                                   |
+| `deselectAllLabel`  | `string`                                                  | `'Deselect all'` | Label of the row once everything listed is selected (used when `selectAll`).                                                                         |
 | `iconLeft`          | `ReactNode`                                               | —          | Icon rendered on the left of the control.                                                                                                                  |
 | `iconRight`         | `ReactNode`                                               | —          | Icon on the right (overrides the default caret).                                                                                                           |
 | `dropdownMenu`      | `boolean`                                                 | `true`     | When `false`, hides the built-in list and disables click-to-open; use with an external picker (e.g. `GroupSelect`) wired to the same `value` / `onChange`. |
@@ -184,10 +187,28 @@ type MultiSelectState = "default" | "hover" | "focus" | "disable" | "error";
 interface MultiSelectOption {
   label: ReactNode;
   value: string | number;
+  /** Greys the option out and blocks interaction. */
   disabled?: boolean;
+  /** When `false`, the option is locked: selected and not removable. Defaults to `true`. */
+  removable?: boolean;
 }
 ```
 
+#### `disabled` vs `removable`
+
+They solve different problems and can be combined:
+
+| | `disabled: true` | `removable: false` |
+| --- | --- | --- |
+| Greyed out | Yes | No — renders like any other selection |
+| Can be selected by the user | No | Yes |
+| Can be deselected once selected | Yes (the flag does not lock an existing selection) | No |
+| Tag shows the ✕ remove button | Yes | No |
+| Included by select-all / deselect-all | No (skipped) | Selected yes, deselected no |
+| Removed by `extraClear` | Yes | No |
+
+Use `removable: false` for a required, default-selected value that should still look like a normal selection.
+
 ## Examples
 
 ### Sizes
@@ -285,6 +306,62 @@ const [selected, setSelected] = useState<MultiSelectValue>([]);
 />;
 ```
 
+### Select all
+
+Enable `selectAll` to show a select-all row at the top of the dropdown, so a long list does not have to be clicked through option by option. Once every selectable listed option is selected, the row flips to deselect-all. Customize the two labels with `selectAllLabel` / `deselectAllLabel`.
+
+Scope rules:
+
+- **Filtered, not global.** With `searchable` active and a query typed, select-all applies only to the options currently listed — it never silently selects options the user cannot see. Deselect-all likewise only clears the listed ones.
+- **`disabled` options are skipped** in both directions.
+- **`removable: false` options are never deselected** — deselect-all leaves them in place.
+
+```tsx
+const options = [
+  { label: "React", value: "react" },
+  { label: "Vue", value: "vue" },
+  { label: "Angular", value: "angular" },
+  { label: "Svelte", value: "svelte" },
+];
+
+const [selected, setSelected] = useState<MultiSelectValue>([]);
+
+<MultiSelect
+  label="Frameworks"
+  options={options}
+  value={selected}
+  onChange={setSelected}
+  selectAll
+  searchable
+  placeholder="Select frameworks"
+/>;
+```
+
+### Locked (non-removable) options
+
+`removeTagsButtons` is component-wide: it either shows the ✕ on every tag or on none. To lock a single value, set `removable: false` on that option instead. Its tag renders without a ✕, clicking the tag does nothing, unchecking it in the dropdown is a no-op, and `extraClear` / deselect-all leave it selected. Unlike `disabled`, it is not greyed out — so a required default reads as a normal selection.
+
+```tsx
+// English is required and must always stay selected; the rest are optional.
+const languages = [
+  { label: "English", value: "en", removable: false },
+  { label: "German", value: "de" },
+  { label: "French", value: "fr" },
+  { label: "Japanese", value: "ja" },
+];
+
+const [selected, setSelected] = useState<MultiSelectValue>(["en"]);
+
+<MultiSelect
+  label="Languages"
+  options={languages}
+  value={selected}
+  onChange={setSelected}
+  extraClear
+  placeholder="Select languages"
+/>;
+```
+
 ### Long option labels
 
 Long, unbreakable option labels (URLs, IDs, tokens) wrap inside the dropdown menu instead of forcing a horizontal scrollbar; the menu width stays pinned to the control.
@@ -316,3 +393,5 @@ const [selected, setSelected] = useState<MultiSelectValue>([]);
 - The dropdown is keyboard navigable; selection state is announced to assistive technology.
 - An `errorMessage` marks the control as invalid for screen readers.
 - When `searchable`, the dropdown's search input exposes an `aria-label` matching `searchPlaceholder`; options filter in memory as the user types (web only).
+- When `selectAll`, the select-all row is exposed as a button whose `aria-label` matches its current action (`selectAllLabel` / `deselectAllLabel`), so the select ↔ deselect flip is announced.
+- A `removable: false` option renders no remove button, so assistive technology does not offer a removal action that would fail.

package/native/index.d.mts

@@ -11,6 +11,19 @@ interface MultiSelectOption {
     label: ReactNode;
     value: string | number;
     disabled?: boolean;
+    /**
+     * When `false`, this option is **locked**: once selected it cannot be
+     * removed. Its tag renders without a remove button, clicking the tag does
+     * nothing, toggling the option off in the dropdown is a no-op, the
+     * `extraClear` clear-all button leaves it in place, and select-all /
+     * deselect-all skips it.
+     *
+     * Unlike `disabled`, a locked option is **not** greyed out — use it for a
+     * required, default-selected value (e.g. a base language that must always
+     * stay selected) that should still look like a normal selection.
+     * @default true
+     */
+    removable?: boolean;
 }
 interface MultiSelectProps extends ThemeOverrideProps {
     /**
@@ -70,12 +83,14 @@ interface MultiSelectProps extends ThemeOverrideProps {
      */
     flexible?: boolean;
     /**
-     * Switch on displaying a remove button in each tag.
+     * Switch on displaying a remove button in each tag. This is the
+     * component-wide default; an individual option can opt out with
+     * `MultiSelectOption.removable: false`.
      * @default true
      */
     removeTagsButtons?: boolean;
     /**
-     * Add clear all button.
+     * Add clear all button. Options with `removable: false` are kept.
      * @default false
      */
     extraClear?: boolean;
@@ -113,6 +128,32 @@ interface MultiSelectProps extends ThemeOverrideProps {
      * @default "No results"
      */
     noOptionsMessage?: string;
+    /**
+     * When true, shows a select-all / deselect-all row at the top of the
+     * built-in dropdown (below the search input when `searchable`).
+     *
+     * Scope is **the options currently listed**: with `searchable` active and a
+     * search query typed, it applies only to the filtered options, matching what
+     * the user can see. Options with `disabled: true` are skipped, and options
+     * with `removable: false` are never deselected. The row flips to
+     * deselect-all once every selectable listed option is selected.
+     *
+     * Ignored when `dropdownMenu` is false.
+     * @default false
+     */
+    selectAll?: boolean;
+    /**
+     * Label of the select-all row. Only used when `selectAll` is true.
+     * @default "Select all"
+     */
+    selectAllLabel?: string;
+    /**
+     * Label of the select-all row once everything listed is selected, at which
+     * point activating it clears the listed selection. Only used when
+     * `selectAll` is true.
+     * @default "Deselect all"
+     */
+    deselectAllLabel?: string;
     /**
      * When false, the built-in options list and backdrop are not shown and the control
      * does not open on click. Use with an external picker (e.g. grouped select) wired

package/native/index.d.ts

@@ -11,6 +11,19 @@ interface MultiSelectOption {
     label: ReactNode;
     value: string | number;
     disabled?: boolean;
+    /**
+     * When `false`, this option is **locked**: once selected it cannot be
+     * removed. Its tag renders without a remove button, clicking the tag does
+     * nothing, toggling the option off in the dropdown is a no-op, the
+     * `extraClear` clear-all button leaves it in place, and select-all /
+     * deselect-all skips it.
+     *
+     * Unlike `disabled`, a locked option is **not** greyed out — use it for a
+     * required, default-selected value (e.g. a base language that must always
+     * stay selected) that should still look like a normal selection.
+     * @default true
+     */
+    removable?: boolean;
 }
 interface MultiSelectProps extends ThemeOverrideProps {
     /**
@@ -70,12 +83,14 @@ interface MultiSelectProps extends ThemeOverrideProps {
      */
     flexible?: boolean;
     /**
-     * Switch on displaying a remove button in each tag.
+     * Switch on displaying a remove button in each tag. This is the
+     * component-wide default; an individual option can opt out with
+     * `MultiSelectOption.removable: false`.
      * @default true
      */
     removeTagsButtons?: boolean;
     /**
-     * Add clear all button.
+     * Add clear all button. Options with `removable: false` are kept.
      * @default false
      */
     extraClear?: boolean;
@@ -113,6 +128,32 @@ interface MultiSelectProps extends ThemeOverrideProps {
      * @default "No results"
      */
     noOptionsMessage?: string;
+    /**
+     * When true, shows a select-all / deselect-all row at the top of the
+     * built-in dropdown (below the search input when `searchable`).
+     *
+     * Scope is **the options currently listed**: with `searchable` active and a
+     * search query typed, it applies only to the filtered options, matching what
+     * the user can see. Options with `disabled: true` are skipped, and options
+     * with `removable: false` are never deselected. The row flips to
+     * deselect-all once every selectable listed option is selected.
+     *
+     * Ignored when `dropdownMenu` is false.
+     * @default false
+     */
+    selectAll?: boolean;
+    /**
+     * Label of the select-all row. Only used when `selectAll` is true.
+     * @default "Select all"
+     */
+    selectAllLabel?: string;
+    /**
+     * Label of the select-all row once everything listed is selected, at which
+     * point activating it clears the listed selection. Only used when
+     * `selectAll` is true.
+     * @default "Deselect all"
+     */
+    deselectAllLabel?: string;
     /**
      * When false, the built-in options list and backdrop are not shown and the control
      * does not open on click. Use with an external picker (e.g. grouped select) wired

package/native/index.js

@@ -435,7 +435,8 @@ var useMultiSelectControl = ({
       stateList: stateList.map((item) => item.value),
       variant,
       size,
-      removeTagsButtons
+      removeTagsButtons,
+      lockedList: stateList.filter((item) => item.removable === false).map((item) => item.value)
     }),
     [stateList, variant, size, removeTagsButtons]
   );
@@ -448,11 +449,18 @@ var useMultiSelectControl = ({
       return true;
     if (prev.stateList.length !== widthsDependencies.stateList.length)
       return true;
+    if (prev.lockedList.length !== widthsDependencies.lockedList.length)
+      return true;
     let i = 0;
     for (const v of prev.stateList) {
       if (v !== widthsDependencies.stateList[i]) return true;
       i++;
     }
+    let j = 0;
+    for (const v of prev.lockedList) {
+      if (v !== widthsDependencies.lockedList[j]) return true;
+      j++;
+    }
     return false;
   };
   const setPlaceholder = () => {
@@ -506,26 +514,28 @@ var useMultiSelectControl = ({
     }
     const content = displayedItems.map((item, index) => {
       const isCount = item.value === COUNT_ITEM_VALUE;
+      const isLocked = !isCount && item.removable === false;
+      const canRemove = !isCount && !isLocked;
       const isReducable = index === 0 && displayStateRef.current === 3 /* Render */ && displayedItemsCount === 0 || flexible;
       if (variant === "tag") {
         return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
           Box,
           {
-            onPress: !isCount ? (e) => {
+            onPress: canRemove ? (e) => {
               e.stopPropagation();
               if (!disabled) removeValue(item.value, e);
             } : void 0,
             style: {
               minWidth: isReducable ? 0 : "fit-content",
               opacity: disabled ? 0.5 : 1,
-              cursor: disabled || isCount ? "not-allowed" : "pointer"
+              cursor: isLocked ? "default" : disabled || isCount ? "not-allowed" : "pointer"
             },
             children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
               import_xui_tag.Tag,
               {
                 size,
                 tone: "primary",
-                onRemove: removeTagsButtons && !isCount ? (e) => {
+                onRemove: removeTagsButtons && canRemove ? (e) => {
                   e?.stopPropagation();
                   if (!disabled) removeValue(item.value, e);
                 } : void 0,
@@ -784,6 +794,7 @@ var initialState = {
   selectedItems: [],
   isOpen: false
 };
+var isLockedOption = (option) => option.removable === false;
 var useMultiSelect = ({
   options,
   value = [],
@@ -791,9 +802,13 @@ var useMultiSelect = ({
 }) => {
   const [state, setState] = (0, import_react4.useState)(initialState);
   const optionsRef = (0, import_react4.useRef)(options);
+  const valuesRef = (0, import_react4.useRef)(value);
   (0, import_react4.useEffect)(() => {
     optionsRef.current = options;
   }, [options]);
+  (0, import_react4.useEffect)(() => {
+    valuesRef.current = state.values;
+  }, [state.values]);
   (0, import_react4.useEffect)(() => {
     const selectedItems = options.filter((opt) => value.includes(opt.value));
     setState((prevState) => ({
@@ -802,9 +817,15 @@ var useMultiSelect = ({
       selectedItems
     }));
   }, [options, value]);
+  const getLockedSelectedValues = () => optionsRef.current.filter(
+    (opt) => isLockedOption(opt) && valuesRef.current.includes(opt.value)
+  ).map((opt) => opt.value);
   const onChoose = (0, import_react4.useCallback)(
     (selectedIds) => {
-      const newValues = optionsRef.current.filter((opt) => selectedIds.includes(String(opt.value))).map((opt) => opt.value);
+      const lockedValues = getLockedSelectedValues();
+      const newValues = optionsRef.current.filter(
+        (opt) => selectedIds.includes(String(opt.value)) || lockedValues.includes(opt.value)
+      ).map((opt) => opt.value);
       const newSelectedItems = optionsRef.current.filter(
         (opt) => newValues.includes(opt.value)
       );
@@ -820,6 +841,8 @@ var useMultiSelect = ({
   const onRemove = (0, import_react4.useCallback)(
     (value2, event) => {
       event?.stopPropagation();
+      const option = optionsRef.current.find((opt) => opt.value === value2);
+      if (option && isLockedOption(option)) return;
       setState((prev) => {
         const newValues = prev.values.filter((v) => v !== value2);
         const newSelectedItems = optionsRef.current.filter(
@@ -836,12 +859,16 @@ var useMultiSelect = ({
     [onChange]
   );
   const onRemoveAll = (0, import_react4.useCallback)(() => {
+    const keptValues = getLockedSelectedValues();
+    const keptItems = optionsRef.current.filter(
+      (opt) => keptValues.includes(opt.value)
+    );
     setState((prevState) => ({
       ...prevState,
-      values: [],
-      selectedItems: []
+      values: keptValues,
+      selectedItems: keptItems
     }));
-    onChange?.([]);
+    onChange?.(keptValues);
   }, [onChange]);
   const onSelectClick = (0, import_react4.useCallback)(() => {
     setState((prevState) => ({
@@ -875,6 +902,8 @@ var Portal = ({ children }) => /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(impo
 // src/MultiSelect.tsx
 var import_jsx_runtime7 = require("react/jsx-runtime");
 var EXTERNAL_MENU_MIN_WIDTH_DEFAULT = 540;
+var SEARCH_ROW_HEIGHT = 60;
+var SELECT_ALL_ROW_HEIGHT = 37;
 var MultiSelect = (0, import_react5.forwardRef)(
   ({
     options,
@@ -901,6 +930,9 @@ var MultiSelect = (0, import_react5.forwardRef)(
     searchable = false,
     searchPlaceholder = "Search",
     noOptionsMessage = "No results",
+    selectAll = false,
+    selectAllLabel = "Select all",
+    deselectAllLabel = "Deselect all",
     testID,
     themeMode,
     themeProductContext
@@ -952,22 +984,33 @@ var MultiSelect = (0, import_react5.forwardRef)(
     const filteredOptions = searchable && searchValue ? options.filter(
       (opt) => getOptionText(opt).toLowerCase().includes(searchValue.toLowerCase())
     ) : options;
+    const selectedIds = values.map(String);
     const menuItems = filteredOptions.map((opt) => {
       const id = String(opt.value);
-      const checked = values.map(String).includes(id);
+      const checked = selectedIds.includes(id);
       return {
         id,
         children: opt.label,
         checked,
-        disabled: opt.disabled
+        disabled: opt.disabled,
+        locked: opt.removable === false
       };
     });
     const handleItemToggle = (id, checked) => {
-      const value2 = options.find((opt) => String(opt.value) === id)?.value;
-      if (value2 === void 0) return;
-      const newValues = checked ? [...values, value2] : values.filter((v) => v !== value2);
+      const option = options.find((opt) => String(opt.value) === id);
+      if (option === void 0) return;
+      if (!checked && option.removable === false) return;
+      const newValues = checked ? [...values, option.value] : values.filter((v) => v !== option.value);
       onChoose(newValues.map(String));
     };
+    const selectAllTargets = filteredOptions.filter((opt) => !opt.disabled);
+    const showSelectAll = selectAll && dropdownMenu && selectAllTargets.length > 0;
+    const areAllTargetsSelected = showSelectAll && selectAllTargets.every((opt) => selectedIds.includes(String(opt.value)));
+    const handleSelectAllToggle = () => {
+      const targetIds = selectAllTargets.map((opt) => String(opt.value));
+      const nextIds = areAllTargetsSelected ? selectedIds.filter((id) => !targetIds.includes(id)) : Array.from(/* @__PURE__ */ new Set([...selectedIds, ...targetIds]));
+      onChoose(nextIds);
+    };
     const controlMenuOpen = dropdownMenu ? isOpen : Boolean(menuOpen);
     const controlOnClick = dropdownMenu ? onSelectClick : onTriggerPress;
     const isScrollOverflow = optionOverflow === "scroll";
@@ -986,6 +1029,7 @@ var MultiSelect = (0, import_react5.forwardRef)(
       overflow: "hidden",
       textOverflow: "ellipsis"
     };
+    const optionsListMaxHeight = maxHeight - (searchable ? SEARCH_ROW_HEIGHT : 0) - (showSelectAll ? SELECT_ALL_ROW_HEIGHT : 0);
     (0, import_react5.useEffect)(() => {
       if (!isWeb || !controlMenuOpen || isDisable || !dropdownMenu) return;
       let rafId = null;
@@ -1119,12 +1163,41 @@ var MultiSelect = (0, import_react5.forwardRef)(
                 )
               }
             ),
+            showSelectAll && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+              Box,
+              {
+                role: "button",
+                "aria-label": areAllTargetsSelected ? deselectAllLabel : selectAllLabel,
+                testID: testID ? `${testID}-select-all` : void 0,
+                paddingHorizontal: sizeStyles.paddingHorizontal,
+                paddingVertical: 8,
+                borderBottomWidth: 1,
+                borderColor: theme.colors.border.secondary,
+                flexDirection: "row",
+                alignItems: "center",
+                onPress: handleSelectAllToggle,
+                hoverStyle: {
+                  backgroundColor: theme.colors.control.input.bgHover
+                },
+                style: { cursor: "pointer" },
+                children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+                  Text,
+                  {
+                    color: theme.colors.content.brand.primary,
+                    fontSize: sizeStyles.fontSize,
+                    fontWeight: "500",
+                    numberOfLines: 1,
+                    children: areAllTargetsSelected ? deselectAllLabel : selectAllLabel
+                  }
+                )
+              }
+            ),
             /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
               Box,
               {
                 paddingVertical: 4,
                 style: {
-                  maxHeight: searchable ? maxHeight - 60 : maxHeight,
+                  maxHeight: optionsListMaxHeight,
                   overflowY: "auto",
                   overflowX: optionListOverflowX,
                   scrollbarWidth: "none"
@@ -1147,6 +1220,7 @@ var MultiSelect = (0, import_react5.forwardRef)(
                 ) : menuItems.map((item, _index) => {
                   const brandColors = theme.colors.control.brand.primary;
                   const contentColors = theme.colors.content;
+                  const isInert = item.locked && item.checked;
                   return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
                     Box,
                     {
@@ -1154,7 +1228,7 @@ var MultiSelect = (0, import_react5.forwardRef)(
                       paddingHorizontal: sizeStyles.paddingHorizontal,
                       paddingVertical: 8,
                       onPress: () => {
-                        if (!item.disabled) {
+                        if (!item.disabled && !isInert) {
                           handleItemToggle(item.id, !item.checked);
                         }
                       },
@@ -1166,7 +1240,7 @@ var MultiSelect = (0, import_react5.forwardRef)(
                         backgroundColor: theme.colors.control.input.bgHover
                       } : void 0,
                       style: {
-                        cursor: item.disabled ? "not-allowed" : "pointer",
+                        cursor: item.disabled ? "not-allowed" : isInert ? "default" : "pointer",
                         opacity: item.disabled ? 0.5 : 1,
                         minWidth: optionRowMinWidth
                       },