Listbox

experimental

The Listbox component presents a list of options and allows a user to select one or more of them. The component uses the ARIA listbox role and implements the W3C ARIA APG Listbox Pattern. Combine it with the Field component to access all functionalities.

Examples

Base

Listboxes are great and accessible select menus for your app, complete with robust support for keyboard navigation and, unlike HTML <select> elements, may contain images. The v-model can be used to bind the selected value. By default the component allows a single option to be chosen.

Accessibility Note:

When assistive technologies present a listbox, the name of an option is calculated by the browser as a flat string. Therefore, the content of an option should not contain any semantic information, such as a heading. In addition, assistive technologies does not provide an accessible way to present a list of interactive elements for the listbox role, such as links, buttons, or checkboxes.

Show code

HTML

<section class="odocs-spaced">
    <o-field label="Select a city">
        <o-listbox v-model="selectedValue">
            <o-list-item label="New York" value="NY" />
            <o-list-item label="Rome" value="RM" />
            <o-list-item label="London" value="LDN" />
            <o-list-item label="Istanbul" value="IST" />
            <o-list-item label="Paris" value="PRS" />
        </o-listbox>
    </o-field>

    <p><b>Selected:</b> {{ selectedValue }}</p>
</section>

JS

import { ref } from "vue";

const selectedValue = ref();

Multiple

When the multiple prop is used, the component become a multi-select listbox that allows multiple options to be selected. The v-model now contains a list of all selected items.

Show code

HTML

<section class="odocs-spaced">
    <o-field label="Select multiple cities">
        <o-listbox v-model="selectedValue" multiple>
            <o-list-item label="New York" value="NY" />
            <o-list-item label="Rome" value="RM" />
            <o-list-item label="London" value="LDN" />
            <o-list-item label="Istanbul" value="IST" />
            <o-list-item label="Paris" value="PRS" />
        </o-listbox>
    </o-field>

    <p><b>Selected:</b> {{ selectedValue }}</p>
</section>

JS

import { ref } from "vue";

const selectedValue = ref([]);

Options

Instead of using the <o-list-item> component directly inside the default slot, an options prop can be defined, which can be used to specify the options programmatically. It accepts several different formats of values:

• An array of primitives ['A', 'B', 'C']
• An object literal with key-value pairs { a: 'A', b: 'B', c: 'C' }
• An array of objects with label and value properties
• Grouped options by adding additional options to the option object.

Note

The options prop works the same as the Select input component options prop.

Show code

HTML

<section class="odocs-spaced">
    <o-field grouped>
        <o-field label="Options">
            <o-listbox v-model="selected" :options="options" />

            <p><b>Selected:</b> {{ selected }}</p>
        </o-field>

        <o-field label="Grouped Options">
            <o-listbox v-model="groupSelected" :options="groupOptions" />

            <p><b>Selected:</b> {{ groupSelected }}</p>
        </o-field>
    </o-field>
</section>

JS

import { ref } from "vue";
import type { OptionsProp, OptionsPropWithGroups } from "@oruga-ui/oruga-next";

const options: OptionsProp<string> = [
    { label: "Flint", value: "flint" },
    { label: "Silver", value: "silver" },
    { label: "Vane", value: "vane" },
    { label: "Billy", value: "billy" },
];

const selected = ref<string>();

const groupOptions: OptionsPropWithGroups<string> = [
    {
        label: "Germany",
        value: "DE",
        options: [
            { label: "Berlin", value: "Berlin" },
            { label: "Frankfurt", value: "Frankfurt" },
            { label: "Hamburg", value: "Hamburg" },
            { label: "Munich", value: "Munich" },
        ],
    },
    {
        label: "USA",
        value: "US",
        options: [
            { label: "Chicago", value: "Chicago" },
            { label: "Los Angeles", value: "Los Angeles" },
            { label: "New York", value: "New York" },
            { label: "San Francisco", value: "San Francisco" },
        ],
    },
    {
        label: "Japan",
        value: "JP",
        options: [
            { label: "Kyoto", value: "Kyoto" },
            { label: "Osaka", value: "Osaka" },
            { label: "Tokyo", value: "Tokyo" },
            { label: "Yokohama", value: "Yokohama" },
        ],
    },
];

const groupSelected = ref<string>();

Filterable

The component provides a built-in filtering feature, which can be enabled by adding the filterable property. A custom filter function can be defined using the filter property. By default, a lowercased label string comparison is performed.

Show code

HTML

<section class="odocs-spaced">
    <o-listbox
        v-model="selectedValue"
        :options="options"
        filterable
        filter-placeholder="Search..."
        empty-label="No Results." />

    <p><b>Selected:</b> {{ selectedValue }}</p>
</section>

JS

import { ref } from "vue";
import type { OptionsProp } from "@/composables";

const selectedValue = ref();

const options: OptionsProp = [
    { label: "New York", value: "NY" },
    { label: "Rome", value: "RM" },
    { label: "London", value: "LDN" },
    { label: "Istanbul", value: "IST" },
    { label: "Paris", value: "PRS" },
];

Slots

A custom header and footer can be added before and after the options list by using the header and footer slots. You can also display content, when no options are visible, either because there are no options or because they are hidden through filtering, using the empty slot.

Show code

HTML

<section class="odocs-spaced">
    <o-field label="Find a name">
        <o-listbox
            :options="[
                {
                    label: 'Jesse Simmons',
                    value: {
                        id: 1,
                        user: { first_name: 'Jesse', last_name: 'Simmons' },
                        date: '2016/10/15 13:43:27',
                        gender: 'Male',
                    },
                },
                {
                    label: 'John Jacobs',
                    value: {
                        id: 2,
                        user: { first_name: 'John', last_name: 'Jacobs' },
                        date: '2016/12/15 06:00:53',
                        gender: 'Male',
                    },
                },
            ]">
            <template #empty> No results found </template>
            <template #header> Header </template>
            <template #footer> Footer </template>
        </o-listbox>
    </o-field>
</section>

Infinite Scroll & Async Data

When having to many options, consider adding a max height using the scrollHeight property, which allows to cap the list at a fixed max-height. This will render a long list of options with a scrollbar. The component will emit a scroll-start or scroll-end event, when the top or bottom of the list is reached. These events can be used to load more options as needed. Consider adding backend-filtering when updating options manually in response to changes in the filter value.

Show code

HTML

<section class="odocs-spaced">
    <o-listbox
        v-model="selectedValue"
        :options="options"
        @scroll-end="getMoreData" />

    <p><b>Selected:</b> {{ selectedValue }}</p>
</section>

JS

import { ref } from "vue";
import type { OptionsPropItem } from "@oruga-ui/oruga-next";

const options = ref<OptionsPropItem<number>[]>(loadData(0));
const selectedValue = ref<number>();

function loadData(start: number): OptionsPropItem<number>[] {
    return Array.from({ length: start + 20 }, (_, i) => ({
        label: `Item #${i}`,
        value: i,
    }));
}

function getMoreData(): void {
    options.value = loadData(options.value.length);
}

Listbox Component

Listbox is used to select one or more values from a list of items.

<o-listbox></o-listbox>

Props

Prop name	Description	Type	Values	Default
animation	Custom animation (transition name)	string	-	From config: listbox: {   animation: "fade" }
ariaLabel	Defines a string value that labels an interactive element.	string	-
ariaLabelledby	Identifier of the underlying input element.	string	-
backendFiltering	Items won't be filtered on clientside, use the filter event to filter in your backend	boolean	-	false
disabled	Interaction is disabled	boolean	-	false
emptyLabel	A label which is displayed when no options are visible	string	-	From config: listbox: {   emptyLabel: undefined }
filter	Custom filter function to filter the items based on the input value - default is label string comparison	((option: unknown, value: string) => boolean)	-
filterDebounce	Number of milliseconds to delay the filter event	number	-	From config: listbox: {   filterDebounce: 400 }
filterIcon	Icon of the column search input	string	-	From config: listbox: {   filterIcon: undefined }
filterPlaceholder	Placeholder of the column search input	string	-	From config: listbox: {   filterPlaceholder: undefined }
filterable	Enable an additional searchbar below the header	boolean	-	false
iconPack	Icon pack to use	string	mdi, fa, fas and any other custom icon pack	From config: listbox: {   iconPack: undefined }
id	Same as native id. Also pass the id to an wrapping o-field component - default is an uuid.	string	-	useId()
v-model	The selected option value, use v-model to make it two-way binding	string|number|object	-
multiple	Allows multiple selections - converts the modelValue into an array	boolean	-
options	Autocomplete options	OptionsPropWithGroups<unknown>	-
override	Override existing theme classes completely	boolean	-
scrollHeight	Height of the listbox, a scrollbar is defined if height of list exceeds this value	number | string	-	From config: listbox: {   scrollHeight: "225" }
selectOnFocus	Select current focused item when focused	boolean	-	false
selectable	Enables item selection	boolean	-	true

Events

Event name	Properties	Description
update:model-value	value unknown | unknown[] - updated modelValue prop	modelValue prop two-way binding
select	value unknown - selected value	on select event - fired before update:modelValue
filter	value string - filter value event Event - native event	on filter change event
focus	event Event - native event	on list focus event
blur	event Event - native event	on list blur event
scroll-start		scrolling inside the list reached the start
scroll-end		scrolling inside the list reached the end

Slots

Name	Description	Bindings
header	Define an additional header
filter	Overridet the filter input	value string - filter input value onChange (input: string, event: Event): void - on filter input change event onKeydown (event: Event): void - on filter input keydown event
default	Define the listbox items here
empty	Define the content to show if the list is empty
footer	Define an additional footer

ListItem Component

An option item used by the listbox component.

<o-list-item></o-list-item>

Props

Prop name	Description	Type	Values	Default
ariaLabel	Defines a string value that labels an interactive element.	string	-
ariaLabelledby	Identifier of the underlying input element.	string	-
disabled	Item is disabled	boolean	-	false
hidden	Define whether the item is visible or not	boolean	-	false
icon	Icon to be shown	string	-
iconPack	Icon pack to use	string	mdi, fa, fas and any other custom icon pack	From config: listbox: {   iconPack: undefined }
iconSize	Icon size	string	small, medium, large	From config: listbox: {   iconSize: undefined }
label	Item label, unnecessary when default slot is used	string	-
override	Override existing theme classes completely	boolean	-
value	Item value (it will be used as v-model of wrapper component) - default is an uuid	string|number|object	-	useId()

Events

Event name	Properties	Description
click	value unknown - value prop data event event - native event	onclick event

Slots

Name	Description	Bindings
default	Override the label, default is label prop	selected boolean - item is selected disabled boolean - item is disabled

Class Inspector

Classes applied to the element:

➜ Want to know how does the Class Inspector work?

Class props inspector is useful to see class props you want to use to customize Oruga components and how they change a component. You can click on Inspect button to find the exact element where a specific class prop acts.

In the Class props inspector there are other columns:

Class prop

This column contains the name of the Class prop you want to inspect.
If you find a name with a link ( ▷ classPropName) this refers to a subitem (e.g. Dropdown Item in Dropdown).

Description

This column contains the description of the Class prop you want to inspect.
👉 This icon indicates some warning, e.g. this Class prop is visible only on mobile.

Props

This column contains a list of props that activate the class, e.g. if a class prop contains disabled prop it means that only when the component has disabled prop.

Suffixes

This column contains all the possible suffixes that you'll receive if you use a function to customize your Class prop.

Class prop	Description	Props	Suffixes
rootClass	Class of the root element.
disabledClass	Class of the root element when disabled.	disabled
selectableClass	Class of the root element when selectable.	selectable
filterableClass	Class of the root element when filterable.	filterable
multipleClass	Class of the root element when multiple.	multiple
headerClass	Class of the header slot wrapper element.
footerClass	Class of the footer slot wrapper element.
emptyClass	Class of the empty slot wrapper element.
filterClass	Class of the filter wrapper element.
listClass	Class of the list element.
▷ itemClass	Class of the item element.
▷ itemSelectableClass	Class of the item element when is selectable.
▷ itemSelectedClass	Class of the item element when is selected.
▷ itemFocusedClass	Class of the item element when is focused.
▷ itemDisabledClass	Class of the item element when is disabled.
inputClasses	Classes to apply on the internal input component. More details here.

Sass Variables

Current theme ➜ Oruga

SASS Variable	Default
$listbox-disabled-opacity	h.useVar("control-disabled-opacity")
$listbox-box-shadow	0 0.5em 1em -0.125em rgba(10, 10, 10, 0.1), 0 0 0 1px rgba(10, 10, 10, 0.02)
$listbox-background-color	h.useVar("control-brackground-color")
$listbox-border-color	h.useVar("control-border-color")
$listbox-border-style	solid
$listbox-border-width	h.useVar("control-border-width")
$listbox-border-radius	h.useVar("border-radius")
$listbox-item-padding	h.useVar("control-spacer") calc(h.useVar("control-spacer") * 2)
$listbox-item-color	h.useVar("font-color")
$listbox-item-font-size	h.useVar("font-size")
$listbox-item-font-weight	h.useVar("font-weight")
$listbox-item-line-height	h.useVar("line-height")
$listbox-item-background-color	transparent
$listbox-item-active-color	h.useVar("primary-invert")
$listbox-item-active-background-color	h.useVar("primary")
$listbox-item-hover-background-color	h.useVar("grey-lighter")
$listbox-item-hover-color	h.useVar("font-color")

See ➜ 📄 SCSS file

Current theme ➜ Bulma

SASS Variable	Default
$listbox-disabled-opacity	0.5
$listbox-item-hover-background-color	css.getVar( "panel-block-hover-background-color")
$listbox-item-active-background-color	css.getVar("primary")

See ➜ 📄 SCSS file

Current theme ➜ Bootstrap

SASS Variable	Default

See ➜ 📄 SCSS file