# MultiSelect A cross-platform multi-select control that lets users pick multiple options from a dropdown list. A dropdown input that allows selecting multiple values simultaneously. Displays the current selections inside the field as text labels or removable tag chips, opens a ContextMenu with checkboxes when clicked, and supports an optional count tag when selections overflow. Built on the same trigger pattern as Select but with multi-value semantics. ### When to use - When the user must choose more than one value from a predefined list — multiple tags, categories, permissions, countries, features - In filter bars where the user applies several filters simultaneously - In forms where a many-to-many relationship must be configured (e.g. assigning roles, selecting supported platforms) - When the full list of options must remain visible and re-selectable without navigating away ### When not to use - When only one value can be selected at a time — use Select - When the number of selectable options is very small (2–4) and all options should be permanently visible — use Checkbox group or ToggleButtonGroup - When the user needs to type free-form tags or values not from a predefined list — use a tag input component - When the user needs to rank or order selections — use a dedicated sortable list ### Content guidelines - Placeholder text — use a concise instructional phrase: *"Select categories"*, *"Choose platforms"*, *"Pick permissions"*. Avoid generic *"Select…"* alone. - Option labels — keep each option label short (1–4 words). Use parallel structure across all options (all nouns or all short phrases). No trailing punctuation. - Option order — alphabetical or most common first. Do not randomise. - Count tag format — always use +N format (e.g. +3, +12). Do not spell out *"3 more"* inside a chip. - Clear button — enable for optional fields. Do not show on required fields — clearing all values on a required field immediately produces a validation error. - Field label — always provide a visible label above the field via FieldGroup. - Error messages — be specific: - *"Please select at least one category"* (required, empty on submit) - *"You can select a maximum of 5 items"* (max exceeded) ### Behaviour guidelines - Multi-select model — multiple values can be selected independently. Selecting one value does not deselect others. Unchecking an option in the ContextMenu removes it from the field. - Individual removal (Tag variant) — when Variant=Tag and Remove button=true, clicking ✕ on a chip removes that specific value from the selection without reopening the dropdown. The ContextMenu reflects the change if it is open. - Clear all — clicking the clear button (✕, Clear button=true) removes all selections at once and returns the field to Fill=False. - Count tag — when selections overflow the visible content area, show a +N count tag. Clicking it opens the dropdown panel so the user can review all selected values. - Opening — clicking the field or pressing Enter / Space / ↓ when focused opens the ContextMenu. The field enters State=Focus; the chevron rotates upward. - Closing — the ContextMenu closes on: clicking outside, pressing Escape, or pressing Tab. Focus returns to the MultiSelect field. - Validation — validate on blur (field loses focus with the dropdown closed) or on form submit. Show State=Error with a message if the selection is invalid (e.g. required field with no selection, or max selection exceeded). - Disabled — State=Disable prevents opening the dropdown. Existing selections remain visible in muted style. - ContextMenu width — the ContextMenu panel must be at least as wide as the MultiSelect field. Never open a narrower panel. - Real-time update — the field content updates as the user checks/unchecks options. Do not batch updates to the field until the dropdown closes. ### Accessibility - MultiSelect must have role=*"combobox"* (or role=*"button"*) with aria-haspopup=*"listbox"* and aria-expanded=*"true"* / *"false"*. - The field must have an accessible name via