@frankhoodbs/combobox-cmp NPM

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.

Version License

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
`--fh-color-outline`	red	Outline color for the active option
`--fh-size-outline`	3px	Outline size for the active option
`--fh-size-outline-offset`	1px	Outline offset size for the active option