Listbox

The Listbox component presents a list of options and allows a user to select one or more of them. The component implements the W3C ARIA APG Listbox Pattern. 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. Combine it with the Field component to access all functionalities.

Examples

Base

Listboxes are a great and accessible select menus for your app, complete with robust support for keyboard navigation.

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

The v-model can be used to bind the selected value. When the multiple prop is used, more than one value can be selected.

Show code

HTML

<section class="odocs-spaced">
    <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>

    <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 define 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 prop. By default, a label string comparison is performed.

Show code

HTML

<section class="odocs-spaced">
    <o-listbox v-model="selectedValue" :options="options" filterable />

    <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 emty 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

The list box is capped on a max-height with the scrollHeight prop. A long list of options will be rendere 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 manually updating options on filter value changes.

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 = [...options.value, ...loadData(options.value.length)];
}

SCSS

.ex-text-grey {
    color: grey;
}

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 is 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 }
itemTag	List item tag name	DynamicComponent	-	From config: listbox: {   itemTag: "li" }
listTag	List tag name	DynamicComponent	-	From config: listbox: {   listTag: "ul" }
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 T | T[] - updated modelValue prop	modelValue prop two-way binding
select	value T - 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 the list reached the start
scroll-end		scrolling the list inside reached it's end

Slots

Name	Description	Bindings
header	Define an additional header
filter	Overridet the filter input	value string - filter input value
default	Place items here
optiongroup	Override the option group	group object - options group item index number - group option index
option	Override the label, default is label prop	option object - option item index number - option index selected boolean - option is selected disabled boolean - option is disabled
empty	Define content for empty state
footer	Define an additional footer

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.
containerClass	Class of the list container element.
listClass	Class of the list element.
▷ itemClass	Class of the item element.
▷ itemSelectedClass	Class of the item element when selected.
▷ itemFocusedClass	Class of the item element when focused.
▷ itemClickableClass	Class of the item element when clickable.
▷ itemDisabledClass	Class of the item element when disabled.
inputClasses	Classes to apply on the internal input component. More details here.

Sass Variables

Current theme ➜ Oruga

The theme does not have any custom variables for this component.

Current theme ➜ Bulma

The theme does not have any custom variables for this component.

Current theme ➜ Bootstrap

The theme does not have any custom variables for this component.