Select
Select allows users to choose a single option from a filterable dropdown list. Supports keyboard navigation, validation states, and dense mode (compact) for space-constrained layouts.
When to use
Do
- ✓Use when users need to pick exactly one value from a list of 5 or more options.
- ✓Use when screen space is limited and a full radio group would overwhelm the layout.
- ✓Use the filter input to help users navigate long option lists quickly.
- ✓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 fewer than 4–5 options — prefer radio buttons for better discoverability.
- ✕Don't use when multiple selections are needed — use diwa-multi-select instead.
- ✕Don't leave the label empty — always provide a meaningful label for accessibility.
- ✕Don't rely solely on colour to communicate validation state — always include a message.
Deselection
To allow users to clear their selection, add an empty diwa-select-option without a value attribute as the first option. This acts as a placeholder and resets the value to undefined when chosen.
<diwa-select label="Favourite fruit" name="fruit">
<diwa-select-option>Please select…</diwa-select-option>
<diwa-select-option value="apple">Apple</diwa-select-option>
<diwa-select-option value="banana">Banana</diwa-select-option>
</diwa-select>Disabled options
Add the disabled attribute to individual options to make them visible but not selectable.
<diwa-select label="Plan" name="plan">
<diwa-select-option value="free">Free</diwa-select-option>
<diwa-select-option value="pro">Pro</diwa-select-option>
<diwa-select-option value="enterprise" disabled>Enterprise (contact sales)</diwa-select-option>
</diwa-select>Controlled usage
Listen to the change event to keep external state in sync. The value property is mutable and reflects the current selection.
const select = document.querySelector('diwa-select');
select.addEventListener('change', (e) => {
console.log(e.detail.name, e.detail.value);
});Label and description
Always provide a concise label that names the thing being selected, not the action. The description prop is appropriate for format hints or constraints that help users choose correctly.
Do
- ✓Label: "Country" (noun describing the option set).
- ✓Description: "Determines your shipping region."
Don't
- ✕Label: "Select a country" (redundant verb phrase).
- ✕Label: "Choose" (too generic to be meaningful).
Validation
Set state to error or success paired with a message that explains the constraint. Never rely on colour alone — the message must be present so the meaning is clear to all users including those using assistive technology.