Vacui UIGitHub repository

Select directive toolkit that offers a seamless and accessible solution for creating custom select/dropdown components.

Select
Loading component...

Installation

Add and import the module into your imports section.

Modules

Loading syntax highlighter...

Standalone directives

Loading syntax highlighter...

Anatomy

Directive's set structure.

vacSelectRoot
vacSelectTrigger
vacSelectValue
vacSelectContent
vacSelectViewport
vacSelectGroup
vacSelectGroupLabel
vacSelectItem
vacSelectItemText
vacSelectItemIndicator
vacSelectSeparator

Input props

SelectRoot Attribute Directive

The root directive that contains the select component parts. Handles the state and bindings. It uses the keyboard navigation directive under the hood, extending its inputs to this directive.

Input Default Type Description
value null SelectValue<T> The selected value(s) of the select component.
open false boolean Whether the select dropdown is open.
disabled false boolean Whether or not the select is disabled.
required false boolean When true, makes the select required before submitting.
multiple false boolean When true, allows multiple selections.
name null string | null The name of the hidden select element for form submission.
compareWith (o1, o2) => o1 === o2 SelectCompareWith<T> A function to compare values. Useful when using complex objects as values.
onEscapeKeyDown — (event: KeyboardEvent) => void Event handler for Escape key press.
Output Returns Description
valueChange SelectValue<T> Event handler emitted when the value of the select changes.
openChange boolean Event handler emitted when the open state changes.
highlightChange SelectValue<T> Event handler emitted when the highlighted item changes.
Attribute Value
data-state "open" | "closed"
data-disabled Shows when disabled

SelectTrigger Attribute Directive

A directive that acts as the trigger button for opening the select dropdown.

Attribute Value
aria-expanded true when open, false otherwise
aria-controls ID of dropdown content
aria-disabled true when disabled, false otherwise
data-state "open" | "closed"
data-disabled Shows when disabled
aria-required true when required, false otherwise

SelectValue Attribute Directive

Directive that displays the selected value(s) or placeholder.

Input Default Type Description
placeholder "" string Placeholder text when no option is selected.
displayWith null (value: string) => string A function to transform how the value is displayed.

SelectContent Attribute Directive

The dropdown content container that holds the select options.

Input Default Type Description
position bottom "top" | "right" | "bottom" | "left" The position of the dropdown relative to the trigger.
positionOffset 0 number Offset distance for the position.
align center "start" | "center" | "end" The alignment of the dropdown.
alignOffset 0 number Offset distance for the alignment.
avoidCollisions true boolean Whether to avoid collisions with the viewport edges.
collisionPadding 10 number | { top?: number; left?: number; bottom?: number; right?: number } Padding between dropdown and viewport edges when avoiding collisions.
Attribute Value
data-position "top" | "right" | "bottom" | "left"
data-align "start" | "center" | "end"
data-state "open" | "closed"
aria-activedescendant ID of highlighted option (non-multiple only)

SelectItem Attribute Directive

Each individual option in the select dropdown.

Input Default Type Description
value* — SelectValue<T> The value of the select item.
disabled false boolean Whether or not the select item is disabled.
Attribute Value
aria-selected true when selected, false otherwise
data-state "checked" | "unchecked"
data-disabled Shows when disabled
data-highlighted Shows when highlighted

SelectGroup Attribute Directive

Groups related select options.

Attribute Value
aria-labelledby ID of group label

SelectItemIndicator Structural Directive

Content inside this directive is rendered only when the item is selected.

SelectVisibility Structural Directive

Controls the content visibility based on the select's open state.

SelectViewport Attribute Directive

Container for scrollable content in the dropdown.

SelectGroupLabel Attribute Directive

Label for option groups.

SelectItemText Attribute Directive

Text content for select items.

SelectSeparator Attribute Directive

A visual separator between items or groups.

State

SelectStateService allows to access the select component properties.

Access directive API with exportAS

We can access the state of the select using a template variable. All the directives expose themselves with the same name. We have access to the directive's attributes and also the state service.

Example

We could use it with any other directive. For example with #select="vacSelectRoot" and access the state.

Loading syntax highlighter...

State API - SelectStateService

Documentation for the select state service API.

Variables

Name Default Type
open false WritableSignal<boolean>
disabled false WritableSignal<boolean>
required false WritableSignal<boolean>
multiple false WritableSignal<boolean>
selectedValues [] WritableSignal<T[]>
items [] WritableSignal<Item<T>[]>
highlighted null WritableSignal<SelectValue<T>>
dataState — ComputedSignal<"open" | "closed">
ariaControls random-id WritableSignal<string>

Methods

Method Return Arguments
toggleOpening void ()
toggleSelection void (value: T)
addInstance void (item: Item<T>)
removeInstance void (value: T)
findLabelByValue string (value: T)
isSelected boolean (value: SelectValue<T>)
addSelectedValue void (value: SelectValue<T>)

Types and interfaces

Loading syntax highlighter...

Accessibility

This Select set of directives is designed in accordance with the WAI-ARIA Authoring Practices Guide. For more details on accessibility features and guidelines, please refer to the WAI-ARIA Combobox Practices. This ensures our component meets modern accessibility standards, providing an inclusive user experience.

Keyboard Navigation

Key Description
Space/Enter Selects the highlighted item.
ArrowUp/ArrowDown Navigates through the list of options.
Escape Closes the select dropdown.
Type characters Searches for options matching the typed characters.
Previous
Radio Group
Next
Separator