Listbox

BsListbox is a component that let users select one or more items from a displayed list.

Added in v2.0.0

Overview

BsListbox uses BsListTile component internally and mimics the HTML List Box: <select size="number"> element. This means that you can add attributes like readonly, or disabled 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.

Selected value:

IMPORTANT

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

Multiple Selection

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

Selected values:

Using Checkbox

In multiple selection mode, the checkbox can be enabled via use-checkbox property.

No data to display.

Selected values:

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.

Updated in v2.2.0

No data to display.

Selected values:

Image Support

<bs-listbox> component supports displaying images or avatars. This feature can be enabled using the show-image property explicitly and use the 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.

Selected value:

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.

Selected value:

Custom List Items

<bs-listbox> list items can be organized in different ways by providing the custom template option-item slot.

No data to display.

Selected value:

CSS Variables

As CSS technology evolves, Vue MDBootstrap introduces local CSS variables on .md-listbox for better customization. And since BsListbox also uses BsListTile internally, it also uses BsListTile's CSS variables.

Updated in v2.2.0

.md-listbox {
  --md-listbox-bg: var(--navigation-background);
  --md-searchbox-bg: #{color.change(colors.$black, $alpha: 0.025)};
  --md-searchbox-active-bg: #{colors.$white};
  --md-searchbox-font-size: 14px;
  --md-searchbox-text-color: currentColor;
  --md-searchbox-border-color: #{colors.$gray-500};
  --md-searchbox-focused-border-color: var(--md-field-active-indicator);
  --md-searchbox-focused-box-shadow: color-mix(in oklch, var(--md-field-active-indicator), transparent 70%);
  --md-searchbox-padding-x: #{vars.$padding-md - 0.25};
  --md-searchbox-padding-y: #{vars.$padding-sm};
}

API Reference

Property	Type	Default	Description
autoload	Boolean	true	Autoload data from the configured dataSource, default is true. v2.0.5
borderless	Boolean	false	Hide the Listbox container borders.
checkbox-color	String	'default'	Sets the Listbox checkbox color. Updated in v2.2.0 Built-in color variants are: default, primary, secondary, success, warning, danger and info.
checkbox-position	String	'left'	Sets the Listbox checkbox position. Valid values are: left, right.
circle-image	Boolean	false	Display image with circle shape for each item that has image property.
color deprecated	String		Apply custom color the Listbox background. Updated in v2.2.0 Use global CSS variable instead.
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.
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.
item-separator-dark	Boolean	false	Set to TRUE when Listbox has dark background color (custom background color) and not in dark theme. v2.2.0
max-height	Number	300	Sets the Listbox container maximum height.
min-search-chars	Number	2	Minimum characters to check before start filtering the Listbox items.
min-search-length	Number	15	Minimum number of items to activate the search box.
model-value v-model	String|Number|String[]|Number[]		Monitored by v-model to maintain this field value.
multiple	Boolean	false	Enable/disable multi selection mode.
not-found-message	String	'Data not found.'	Sets the not found message when searching returns no result.
readonly	Boolean	false	Put the component in readonly state and sets the <select> element readonly attribute.
rounded-image	Boolean	false	Display image with rounded shape for each item that has image property.
search-label	String	'Search...'	The search box text label.
search-text v-model	String		Monitored by v-model to maintain the search box keyword.
show-image	Boolean	false	Show or hide image if Listbox item's object contains image property.
use-checkbox	Boolean	false	Use checkbox for multi selection mode.

Name	Arguments	Description
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|String[]|Number[])	Triggers when the Listbox value is updated.
update:search-text	(value:String)	Triggers when the Listbox search value is updated.
update:selected-value	(selected:Object[])	Triggers when the Listbox selected value is updated.

Name	Arguments	Description
option-item	(item:Object, index:Number)	The outlet slot used to customize listbox items appearance.
empty-data-msg		The outlet slot used to place custom message when listbox is empty.
not-found-msg		The outlet slot used to place custom message when filtering listbox items returns no result.