@xsolla/xui-multi-select 0.216.0 → 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