Combobox

BsCombobox is a form field component that let users select one or more items from a dropdown displayed list.

Overview

BsCombobox uses BsListbox and BsPopover components internally and mimics like HTML combobox: <select> element. This means that you can add attributes like readonly, disabled, required and it will react to them to give the best experience. You can also use v-model directive to create two-way data bindings on the model-value property.

IMPORTANT

Do not use the model-value property when using v-model.

Style Variants

You can style <bs-combobox> to your own preference or use a style variant based on Google Material Design 2 or Material Design 3 specifications.

Default

You can style <bs-combobox> that follows Google Material Design 2 specifications by using floating-label property explicitly.

Filled

Use filled property explicitly to enable <bs-combobox> with solid fill style. And when combined with floating-label property, <bs-combobox> will have a style that follows the Google Material Design 3 specifications.

Outlined

Use outlined property explicitly to enable <bs-combobox> with outline style. And when combined with floating-label property, <bs-combobox> will have a style that follows the Google Material Design 3 specifications.

Clearable

Define the clear-button property explicitly, so that the field value can be cleared easily.

Multiple Selection

<bs-combobox> support multiple selection. Multiple selection feature can be enabled using the multiple property explicitly.

Checkbox Position and Color

In multiple selection mode, the checkbox color can be changed via checkbox-color property and the position can be changed via checkbox-position property. Valid values for this property are: left (default), right. If these property is not defined, then default value will be used.

TIP

Any MDBootstrap Color variants and Material Color variants can be applied to the checkbox-color property.

Chips Mode

In multiple selection mode, the selected items can be display as chips. Use property chip-enabled explicitly to display the selected items as chips. Additionally you can use chip-color property to set the chips color and chip-outlined or chip-pill to style the chips appearance.

Updated on v2.0.0

TIP

Any MDBootstrap Color variants and Material Color variants can be applied to the chip-color property.

Cascade Support

<bs-combobox> component supports cascade selection or parent-child relationship
when there are two or more <bs-combobox> components.

To activate this feature, sets the parent-value property on child component to the parent component model-value and use the cascadeField property on the configuration schema to point to the field that has relation to the parent. By default, the value of cascadeField property is set to parent.

Image Support

<bs-combobox> component supports displaying images or avatars. This feature can be enabled using the show-image property explicitly and use imageField property on the configuration schema to point to the image field in the datasource. By default, the value of property imageField is set to image.

Image Size And Shape

The size of images can be controlled via image-size property. Sets this property to the desired numbers of pixels and the image will displayed according to this value. And use rounded-image or circle-image property to change its shape.

Hover Display Support

The Listbox popup can be displayed using hover instead of clicking with the open-on-hover property.

Help Text

The help-text property on <bs-combobox> adds an help text beneath the combobox. And sets the persistent-help-text property to false will make the help text visible only when the combobox is focused.

Icons

The properties prepend-icon, prepend-icon-outer, append-icon and append-icon-outer provides the ability to add icon to <bs-combobox>.

Use any valid android icon name from Google Material Symbols with or without a suffix. Valid suffixes are: _outlined, _rounded, _sharp, _filled, _outlined_filled, _rounded_filled, and _sharp_filled. Suffix _filled and _outlined_filled will display the same icon style variant.

Updated on v2.1.0

INFO

Since Vue MDBootstrap v2.1.0, Google Material Icons are replaced with Google Material Symbols.

Usage Example

The following is an example that demonstrate more advanced use of the <bs-combobox> with form validation.

CSS Variables

Added since v2.0.0

--md-field-active-border-color: rgb(var(--md-field-active-indicator));
--md-field-active-border-width: 2px;
--md-field-color-bg: currentColor;
--md-field-border-color: currentColor;
--md-field-border-width: 1px;
--md-field-floating-label-color: var(--md-field-label-color);
--md-field-label-color: currentColor;

// global css variables
--md-field-primary-indicator-rgb: 98, 0, 238;
--md-field-primary-indicator: rgb(var(--md-field-primary-indicator-rgb));
--md-field-accent-indicator-rgb: 185,156,225;
--md-field-accent-indicator: rgb(var(--md-field-accent-indicator-rgb));
--md-field-active-indicator: var(--md-field-primary-indicator-rgb);

API Reference

Property	Type	Default	Description
action-icon-variant	String	'outlined'	Sets the action icon style variant. Valid values are: outlined, rounded, sharp, filled, outlined_filled, rounded_filled, and sharp_filled. Updated on v2.1.0
append-icon	String		Sets icon to display at the inner right side. Updated on v2.1.0 Use any valid android icon name from Google Material Symbols with or without a suffix. Valid suffixes are: _outlined, _rounded, _sharp, _filled, _outlined_filled, _rounded_filled, and _sharp_filled.
append-icon-outer	String		Sets icon to display at the outer right side. Updated on v2.1.0 Use any valid android icon name from Google Material Symbols with or without a suffix. Valid suffixes are: _outlined, _rounded, _sharp, _filled, _outlined_filled, _rounded_filled, and _sharp_filled.
autofocus	Boolean	false	Autofocus field when this component is mounted.
check-option-color deprecated	String		Use checkbox-color instead.
check-option-position deprecated	String		Use checkbox-position instead.
checkbox-color	String	'default-color'	Sets the Listbox checkbox color. Any MDBootstrap Color variants and Material Color variants can be used. v2.0.0
checkbox-position	String	'left'	Sets the Listbox checkbox position. Valid values are: left, right. v2.0.0
chip-color	String	'grey'	The default Chips color to apply. Any MDBootstrap Color variants and Material Color variants can be used.
chip-enabled	Boolean	false	Enable/disable Chip selection mode for the selected items.
chip-outlined	Boolean	false	Render the Chips with outlined style.
chip-pill	Boolean	false	Render the Chips with rounded-pill style. v2.0.0
circle-image	Boolean	false	Display image with circle shape for each item that has image property.
clear-button	Boolean	false	Sets auto show the clear button.
data-source required	TDataSource		Sets the data source configuration.
disabled	Boolean	false	Put the component in disabled state and sets the <select> element disabled attribute.
empty-data-message	String	'No data to display.'	Sets the no data message when the Listbox is empty.
external-validator deprecated	TValidator		Use validator instead.
filled	Boolean	false	Create the component with solid fill style appearance. See Google Material Design for details.
floating-label	Boolean	false	Create the component with floating field label. See Google Material Design for details.
help-text	String		The help text to display below the field component.
id	String		Sets <select> element ID attribute. This property value is auto generates.
image-size	Number	48	Define the image size for each Listbox items when show-image is enabled.
item-separator	Boolean	false	Show or hide the Listbox item separator.
listbox-color	String	'white'	Define the Listbox background color. Any MDBootstrap Color variants and Material Color variants can be used.
listbox-max-height	Number	300	Sets the Listbox container maximum height. v2.0.0
listbox-min-width	Number		Sets the Listbox container minimum width. v2.0.0
listbox-search-label	String	'Search...'	The search box text label. v2.0.0
min-search-chars	Number	2	Minimum characters to check before start filtering the Listbox items. v2.0.0
min-search-length	Number	15	Minimum number of items to activate the search box. v2.0.0
model-value v-model	String/Number/Array		Monitored by v-model to maintain this field value. v2.0.0
multiple	Boolean	false	Enable/disable multiple selection mode.
name	String		Sets <select> element name attribute.
not-found-message	String	'Data not found.'	Sets the not found message when searching returns no result.
open-on-hover	Boolean	false	Display the Listbox when mouse hover the component.
outlined	Boolean	false	Create the component with outline style appearance. See Google Material Design spec.
parent-value	String/Number		Sets the cascading combobox parent value.
persistent-help-text	Boolean	true	Keeps help text visible when the component is not focused.
placeholder	String		Sets the field placeholder.
popover-max-height deprecated	Number		Use listbox-max-height instead.
popover-min-width deprecated	Number		Use listbox-min-width instead.
prepend-icon	String		Sets icon to display at the inner left side. Updated on v2.1.0 Use any valid android icon name from Google Material Symbols with or without a suffix. Valid suffixes are: _outlined, _rounded, _sharp, _filled, _outlined_filled, _rounded_filled, and _sharp_filled.
prepend-icon-outer	String		Sets icon to display at the outer left side. Updated on v2.1.0 Use any valid android icon name from Google Material Symbols with or without a suffix. Valid suffixes are: _outlined, _rounded, _sharp, _filled, _outlined_filled, _rounded_filled, and _sharp_filled.
readonly	Boolean	false	Put the component in readonly state and sets the <select> element readonly attribute.
required	Boolean	false	Sets <select> element required attribute.
rounded-image	Boolean	false	Display image with rounded shape for each item that has image property.
show-image	Boolean	false	Show or hide image if Listbox item's object contains image property.
transition	string	'scale'	Transition animation when showing the Listbox.
validation-icon	Boolean	false	Display validation icon or not, when this field has been validated. v2.0.0
validator	TValidator		The configuration options to integrate external validator plugin to validate this field value. v2.0.0

Name	Arguments	Description
clear		Triggers after this field value is cleared. v2.0.0
close		Triggers when the Popover is hiding.
open		Triggers when the Popover is show.
data-bind	( items:Object[])	Triggers after the data has been fetched.
data-error	( error:Object)	Triggers when error loading data items.
data-filter	( items:Object[])	Triggers after the listbox data items is filtered.
deselect	( value:Object)	Triggers when an item is deselected.
select	( value:Object)	Triggers when an item is selected.
update:model-value	( value:String/Number/Array)	Triggers when the combobox value is updated. v2.0.0
update:selected-value	( selected:Object[])	Triggers when the combobox selected value is updated. v2.0.0

Name	Arguments	Description
default		The outlet slot used to place the field label.
append-inner		The outlet slot used to place custom icon or component at the inner right side. v2.0.0
append-outer		The outlet slot used to place custom icon or component at the outer right side. v2.0.0
empty-data-msg		The outlet slot used to place custom message when listbox is empty. v2.0.1
not-found-msg		The outlet slot used to place custom message when filtering listbox items returns no result. v2.0.1
help-text		The outlet slot used for custom help text. v2.0.0
prepend-inner		The outlet slot used to place custom icon or component at the inner left side. v2.0.0
prepend-outer		The outlet slot used to place custom icon or component at the outer left side. v2.0.0
option-item	( item:Object, index:Number)	The outlet slot used to customize listbox items appearance. v2.0.0

TValidator

The validator configuration option has properties as described below:

Property	Type	Description
validators	Record<String,Boolean>	External validator plugin validation result.
messages	Record<String,String>	Validation message for each validation types.
hasError	Boolean	An indicator that tells the field value pass the validation or not.
dirty	Boolean	Value comes from validator plugin that indicate the field is dirty or not.

All properties are mandatory.

NOTE

Vue MDBootstrap does not include form validation by default, we leave that up to the 3rd party form validation plugin. As of now, Vuelidate has been fully tested with our component library.