@frankhoodbs/combobox-cmp

Combobox Component

A flexible and accessible combobox component tailored for Vue 3. This combobox is designed for both visual appeal and usability, adhering to ARIA guidelines. The component is extensible, allowing for easy integration and customization of its design to match your project.

Generic types

• T: The currently selected value from the combobox options. T can be of any type, based on the types of values you've provided within your options. Often, T will match the value type within the Option interface.

• Option object must extend the following interface:

interface OptionItem {
  label: string;
  value: T;
  [key: string]: any;
}

This means that while every option object must have at least the value and label properties, it can also have additional properties.

Props

Prop	Type	Default	Description
model-value	T	-	The current value of the combobox
data-options	OptionItem[]	-	Array of options for the combobox
data-id-prefix	string	-	required Prefix for all the id attributes
data-aria-labelledby	string	-	The ID of the element that labels the combobox
data-disabled	boolean	false	Whether the combobox is disabled or not
data-invalid	boolean	false	If true, indicates the combobox's value is invalid
data-placement	@floating-ui Placement	bottom-start	Placement of the combobox list relative to the combobox
data-fallback-placements	@floating-ui Placement[]	-	Array of alternative placements for the floating menu in case the desired placement is not possible
data-offset	number	0	Offset (in pixels) between the button and the floating menu

Events

Event	Payload Type	Description
'update:modelValue'	T	Emits the selected value from the combobox options

Slots

Slot	Props	Description
combobox	{ label: string, expanded: boolean, option: OptionItem }	Slot for customizing the combobox content
option	{ option: OptionItem, index: number }	Slot for customizing individual combobox options

CSS Custom Properties

Custom Property	Default Value	Description
--combobox-cmp-combobox-background	transparent	Background of the combobox
--combobox-cmp-combobox-color	black	Text color of the combobox
--combobox-cmp-combobox-border-width	0px	Width of the combobox border
--combobox-cmp-combobox-border-color	transparent	Color of the combobox border
--combobox-cmp-combobox-border-radius	0px	Border radius of the combobox
--combobox-cmp-disabled-opacity	0.5	Opacity of the combobox when disabled
--combobox-cmp-listbox-background	white	Background of the combobox list
--combobox-cmp-listbox-color	black	Text color of the combobox list
--combobox-cmp-listbox-border-width	1px	Width of the combobox list border
--combobox-cmp-listbox-border-color	black	Color of the combobox list border
--combobox-cmp-listbox-border-radius	4px	Border radius of the combobox list
--combobox-cmp-listbox-max-height	200px	Maximum height of the combobox list
--combobox-cmp-option-active-background	grey	Background of an active or hovered option
--combobox-cmp-option-selected-background	yellow	Background of a selected option
--combobox-cmp-transition-duration	0.3s	Transition duration
--combobox-cmp-transition-timing-function	ease-in-out	Transition timing function
--combobox-cmp-listbox-width	100%	Width of the combobox list
--combobox-cmp-listbox-min-width	0	Minimum width of the combobox list
--combobox-cmp-listbox-max-width	none	Maximum width of the combobox list
--combobox-cmp-color-outline	red	Outline color for the active option
--combobox-cmp-size-outline	3px	Outline size for the active option
--combobox-cmp-size-outline-offset	1px	Outline offset size for the active option