Multi Select

Multi Select allows users to choose one or more options from a filterable dropdown list. Supports keyboard navigation, validation states, and dense mode (compact) for space-constrained layouts.

When to use

✓Use when users need to select multiple values from a long list (more than ~5 options).
✓Use when screen space is limited and a full list would overwhelm the layout.
✓Use the filter input for lists with 8+ options to reduce scrolling.
✓Use dense mode (compact) in toolbars, table headers, or sidebars.
✓Use error state with a descriptive message when validation fails.

Don't

✕Don't use for single-selection — use diwa-select or a radio group instead.
✕Don't use for fewer than 3 options — a checkbox group is clearer.
✕Don't hide the label without providing an accessible name.
✕Don't show validation state without a visible message explaining the issue.
✕Don't pre-select options unless the defaults are well-justified by the use case.

Controlled pattern

diwa-multi-select is semi-controlled: child options update their selected prop on user interaction, and the parent emits a change event with the full value array. Listen to this event to keep external state in sync.

// Vanilla JS — listen for the change event
const el = document.querySelector('diwa-multi-select');
el.addEventListener('change', (e) => {
  console.log('selected values:', e.detail.value);
  // e.detail = { name: 'fruits', value: ['apple', 'cherry'] }
});

// React 19 — wire via onchange prop
<diwa-multi-select
  label="Fruits"
  name="fruits"
  onchange={(e) => setFruits(e.detail.value)}
>
  <diwa-multi-select-option value="apple">Apple</diwa-multi-select-option>
</diwa-multi-select>

Pre-selecting options

Set the selected attribute on individual diwa-multi-select-option elements to pre-select them on load. The parent will pick these up and include their values.

<diwa-multi-select label="Roles" name="roles">
  <diwa-multi-select-option value="viewer" selected>Viewer</diwa-multi-select-option>
  <diwa-multi-select-option value="editor">Editor</diwa-multi-select-option>
  <diwa-multi-select-option value="admin">Admin</diwa-multi-select-option>
</diwa-multi-select>

Programmatic control

Use the public open() and close() methods to control the dropdown from external code.

const el = document.querySelector('diwa-multi-select');
await el.open();   // opens the dropdown
await el.close();  // closes the dropdown

Label and description

Always provide a concise label that describes the group of options, not the action of selecting. Use the description prop for supplementary guidance, such as a character limit or format hint.

✓Label: "Programming languages" (noun phrase describing the options).
✓Description: "Select all that apply."

Don't

✕Label: "Select programming languages" (verb phrase — redundant).
✕Label: "Options" (too generic to be meaningful).

Validation

Set state to error or success together with a message that explains the constraint or confirms the value is valid. Never rely on colour alone to communicate state — the message ensures the meaning is conveyed to all users.

Dense mode (compact)

Dense mode (compact) reduces trigger and option row heights. Use it in dense layouts such as toolbars and data-table filter rows. Checkbox size scales proportionally to remain legible. Avoid dense mode in primary form contexts where users need to focus on the field.