Autocomplete

The Autocomplete input component allows you to search through a list of options. It is an advanced input that provides suggestions as the user types. Based on the Dropdown component, the component implements the W3C ARIA APG Combobox Pattern. Use it with the Field component to access all functionalities.

Examples

Base

Show code

HTML

<section class="odocs-spaced">
    <o-field label="Find a JS framework">
        <o-autocomplete
            v-model="selected"
            :options="options"
            rounded
            expanded
            placeholder="e.g. jQuery"
            icon="search"
            clearable
            open-on-focus>
        </o-autocomplete>

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

JS

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

const options: OptionsProp<string> = [
    "Angular",
    "Angular 2",
    "Aurelia",
    "Backbone",
    "Ember",
    "jQuery",
    "Meteor",
    "Node.js",
    "Polymer",
    "React",
    "RxJS",
    "Vue.js",
];

const selected = ref();

Selection

The autocomplete input can only contain one item at a time. For the multiple selection version, see the Taginput component.

Show code

HTML

<section class="odocs-spaced">
    <o-field grouped multiline>
        <o-switch v-model="keepFirst">Keep first</o-switch>
        <o-switch v-model="keepOpen">Keep open</o-switch>
        <o-switch v-model="openOnFocus">Open on focus</o-switch>
        <o-switch v-model="selectOnClose">Select on close</o-switch>
        <o-switch v-model="clearOnSelect">Clear on Select</o-switch>
        <o-button @click="changeselection">
            Set '{{ options[0] }}' selected
        </o-button>
    </o-field>

    <o-field label="Find a name">
        <o-autocomplete
            v-model="selected"
            :options="options"
            placeholder="e.g. Vue"
            icon="search"
            :keep-first="keepFirst"
            :open-on-focus="openOnFocus"
            :keep-open="keepOpen"
            :clear-on-select="clearOnSelect"
            :select-on-close="selectOnClose">
            <template #empty> No results found </template>
        </o-autocomplete>

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

JS

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

const keepFirst = ref(false);
const keepOpen = ref(true);
const openOnFocus = ref(true);
const selectOnClose = ref(false);
const clearOnSelect = ref(false);

const options: OptionsProp<string> = [
    "Angular",
    "Angular 2",
    "Aurelia",
    "Backbone",
    "Ember",
    "jQuery",
    "Meteor",
    "Node.js",
    "Polymer",
    "React",
    "RxJS",
    "Vue.js",
];

const selected = ref();

function changeselection(): void {
    selected.value = options[0];
}

Options

The options prop can accept 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>
    <o-field label="Options List">
        <o-autocomplete
            v-model="selected"
            :options="options"
            placeholder="Find a name..."
            open-on-focus>
        </o-autocomplete>

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

JS

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

const options: OptionsProp = [
    {
        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",
        },
    },
    {
        label: "Tina Gilbert",
        value: {
            id: 3,
            user: { first_name: "Tina", last_name: "Gilbert" },
            date: "2016/04/26 06:26:28",
            gender: "Female",
        },
    },
    {
        label: "Clarence Flores",
        value: {
            id: 4,
            user: { first_name: "Clarence", last_name: "Flores" },
            date: "2016/04/10 10:28:46",
            gender: "Male",
        },
    },
    {
        label: "Anne Lee",
        value: {
            id: 5,
            user: { first_name: "Anne", last_name: "Lee" },
            date: "2016/12/06 14:38:38",
            gender: "Female",
        },
    },
    {
        label: "Sara Armstrong",
        value: {
            id: 6,
            user: { first_name: "Sara", last_name: "Armstrong" },
            date: "2016/09/23 18:50:04",
            gender: "Female",
        },
    },
    {
        label: "Anthony Webb",
        value: {
            id: 7,
            user: { first_name: "Anthony", last_name: "Webb" },
            date: "2016/08/30 23:49:38",
            gender: "Male",
        },
    },
    {
        label: "Andrew Greene",
        value: {
            id: 8,
            user: { first_name: "Andrew", last_name: "Greene" },
            date: "2016/11/20 14:57:47",
            gender: "Male",
        },
    },
    {
        label: "Russell White",
        value: {
            id: 9,
            user: { first_name: "Russell", last_name: "White" },
            date: "2016/07/13 09:29:49",
            gender: "Male",
        },
    },
    {
        label: "Lori Hunter",
        value: {
            id: 10,
            user: { first_name: "Lori", last_name: "Hunter" },
            date: "2016/12/09 01:44:05",
            gender: "Female",
        },
    },
    {
        label: "Ronald Wood",
        value: {
            id: 11,
            user: { first_name: "Ronald", last_name: "Wood" },
            date: "2016/12/04 02:23:48",
            gender: "Male",
        },
    },
    {
        label: "Michael Harper",
        value: {
            id: 12,
            user: { first_name: "Michael", last_name: "Harper" },
            date: "2016/07/27 13:28:15",
            gender: "Male",
        },
    },
    {
        label: "George Dunn",
        value: {
            id: 13,
            user: { first_name: "George", last_name: "Dunn" },
            date: "2017/03/07 12:26:52",
            gender: "Male",
        },
    },
    {
        label: "Eric Rogers",
        value: {
            id: 14,
            user: { first_name: "Eric", last_name: "Rogers" },
            date: "2016/06/07 05:41:52",
            gender: "Male",
        },
    },
    {
        label: "Juan Meyer",
        value: {
            id: 15,
            user: { first_name: "Juan", last_name: "Meyer" },
            date: "2017/02/01 04:56:34",
            gender: "Male",
        },
    },
    {
        label: "Silvia Rosa",
        value: {
            id: 16,
            user: { first_name: "Silvia", last_name: "Rosa" },
            date: "2017/01/26 11:50:04",
            gender: "Female",
        },
    },
    {
        label: "Lori Cunningham",
        value: {
            id: 17,
            user: { first_name: "Lori", last_name: "Cunningham" },
            date: "2016/05/01 10:00:56",
            gender: "Female",
        },
    },
    {
        label: "Charle Graham",
        value: {
            id: 18,
            user: { first_name: "Charles", last_name: "Graham" },
            date: "2016/05/31 06:43:30",
            gender: "Male",
        },
    },
    {
        label: "Henry Morrison",
        value: {
            id: 19,
            user: { first_name: "Henry", last_name: "Morrison" },
            date: "2016/09/27 16:15:44",
            gender: "Male",
        },
    },
    {
        label: "Albert Mendoza",
        value: {
            id: 20,
            user: { first_name: "Albert", last_name: "Mendoza" },
            date: "2016/08/08 05:29:24",
            gender: "Male",
        },
    },
    {
        label: "Ruby Snyder",
        value: {
            id: 21,
            user: { first_name: "Ruby", last_name: "Snyder" },
            date: "2017/04/01 12:04:39",
            gender: "Female",
        },
    },
];

const selected = ref();

Show code

HTML

<section>
    <o-field label="Grouped Options">
        <o-autocomplete
            v-model="groupSelected"
            :options="groupOptions"
            placeholder="Find a name grouped by film..."
            open-on-focus>
            <template #header>Film Character Groups</template>
        </o-autocomplete>

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

JS

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

const groupOptions: OptionsPropWithGroups<string> = [
    {
        label: "Black Sails",
        attrs: { disabled: true },
        options: [
            { label: "Flint", value: "flint" },
            { label: "Silver", value: "silver" },
            { label: "Vane", value: "vane" },
            { label: "Billy", value: "billy" },
            { label: "Jack", value: "silver", attrs: { disabled: true } },
        ],
    },
    {
        label: "Breaking Bad",
        attrs: { disabled: true },
        options: {
            heisenberg: "Heisenberg",
            jesse: "Jesse",
            saul: "Saul",
            mike: "Mike",
        },
    },
    {
        label: "Game of Thrones",
        attrs: { disabled: true },
        options: [
            "Tyrion Lannister",
            "Jamie Lannister",
            "Daenerys Targaryen",
            "Jon Snow",
        ],
    },
];

const groupSelected = ref();

Slots

A header and a footer can be added to the options list by using the header and footer slots. The header and footer can be made clickable by adding the selectable-header and selectable-footer props. Clicking them will clear the input.

Show code

HTML

<section class="odocs-spaced">
    <o-field label="Find a name">
        <o-autocomplete
            :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',
                    },
                },
            ]"
            open-on-focus
            keep-open
            keep-first
            selectable-header
            selectable-footer>
            <template #empty> No results found </template>
            <template #header> Header </template>
            <template #footer> Footer </template>
        </o-autocomplete>
    </o-field>
</section>

Infinite Scroll & Async Data

When check-scroll prop is set, the component will emits the scroll-start and scroll-end events. These events can be used to load more options as needed. Consider adding backend-filtering when manually updating options on input values changes.

Note

The autocomplete component does not have a default slot for defining options. The default slot is used to override the option element template.

Show code

HTML

<section class="odocs-spaced">
    <o-field label='Find a movie in the "The Movie Database (TMDB)"'>
        <o-autocomplete
            v-model="selected"
            :options="options"
            placeholder="e.g. Fight Club"
            expanded
            check-scroll
            backend-filtering
            :debounce="500"
            @input="getAsyncData"
            @scroll-end="getMoreAsyncData">
            <template #default="{ value }">
                <div class="media">
                    <div class="media-left">
                        <img
                            width="32"
                            :src="`https://image.tmdb.org/t/p/w500/${value.poster_path}`" />
                    </div>
                    <div class="media-content">
                        {{ value.title }}
                        <br />
                        <small>
                            Released at {{ value.release_date }}, rated
                            <b>{{ value.vote_average }}</b>
                        </small>
                    </div>
                </div>
            </template>

            <template v-if="page > totalPages || !options.length" #footer>
                <span class="ex-text-grey">
                    Thats it! No more movies found.
                </span>
            </template>
        </o-autocomplete>

        <p><b>Selected:</b> {{ selected?.title }}</p>
    </o-field>
</section>

JS

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

const isFetching = ref(false);
const page = ref(1);
const totalPages = ref(1);

const options = ref<OptionsPropItem<any>[]>([]);
const selected = ref<any>();
const value = ref("");

async function getAsyncData(_value: string): Promise<void> {
    if (value.value !== _value) {
        value.value = _value;
        options.value = [];
        page.value = 1;
        totalPages.value = 1;
    }

    // String cleared
    if (!_value.length) {
        options.value = [];
        page.value = 1;
        totalPages.value = 1;
        return;
    }

    // Reached last page
    if (page.value > totalPages.value) {
        return;
    }

    isFetching.value = true;
    try {
        const _data = await fetch(
            `https://api.themoviedb.org/3/search/movie?api_key=bb6f51bef07465653c3e553d6ab161a8&query=${_value}&page=${page.value}`,
        ).then((response) => response.json());

        const movies: OptionsPropItem[] = _data.results.map((v) => ({
            value: v,
            label: v.title,
        }));

        options.value = [...options.value, ...movies];
        page.value += 1;
        totalPages.value = _data.total_pages;
    } catch (err) {
        console.error(err);
    } finally {
        isFetching.value = false;
    }
}

function getMoreAsyncData(): void {
    getAsyncData(value.value);
}

SCSS

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

Autocomplete component

Extended input that provide suggestions while the user types.

<o-autocomplete></o-autocomplete>

Props

Prop name	Description	Type	Values	Default
active	The active state of the dropdown, use v-model:active to make it two-way binding	boolean	-	false
animation	Transition name to apply on dropdown list	string	-	From config: autocomplete: {   animation: "fade" }
autocomplete	Native options to use in HTML5 validation	string	-	From config: autocomplete: {   autocomplete: "off" }
backendFiltering	Options won't be filtered based on the input value on clientside	boolean	-	From config: autocomplete: {   backendFiltering: false }
checkScroll	Makes the component check if list reached scroll start or end and emit scroll events	boolean	-	From config: autocomplete: {   checkScroll: false }
clearIcon	Icon name to be added on the clear button	string	-	From config: autocomplete: {   clearIcon: "close-circle" }
clearOnSelect	Clear input text on select	boolean	-	From config: autocomplete: {   clearOnSelect: false }
clearable	Add a button/icon to clear the inputed text	boolean	-	From config: autocomplete: {   clearable: false }
customValidity	Custom HTML 5 validation error to set on the form control	string | ((currentValue: unknown, state: ValidityState) => string)	-
debounce	Number of milliseconds to delay before to emit input event	number	-	From config: autocomplete: {   debounce: 400 }
desktopModal	Dropdown content (items) are shown into a modal on desktop	boolean	-	From config: dropdown: {   desktopModal: false }
disabled	Same as native input disabled	boolean	-	false
expanded	Makes input full width when inside a grouped or addon field	boolean	-	false
filter	Function to filter the option based on the input value - default is label string comparison	((option: unknown, value: string) => boolean)	-
icon	Icon to be shown	string	-	From config: autocomplete: {   icon: undefined }
iconClickable	Makes the icon clickable	boolean	-	false
iconPack	Icon pack to use	string	mdi, fa, fas and any other custom icon pack	From config: autocomplete: {   iconPack: undefined }
iconRight	Icon to be added on the right side	string	-	From config: autocomplete: {   iconRight: undefined }
iconRightClickable	Make the icon right clickable	boolean	-	false
iconRightVariant	Variant of right icon	string	-
input	The value of the inner input, use v-model:input to make it two-way binding	string	-	""
itemTag	Menu item tag name	DynamicComponent	-	From config: autocomplete: {   itemTag: "div" }
keepFirst	The first option will always be focused (easier to just hit enter or tab)	boolean	-	From config: autocomplete: {   keepFirst: false }
keepOpen	Keep open dropdown list after select	boolean	-	From config: autocomplete: {   keepOpen: false }
maxHeight	Max height of dropdown content	number | string	-	From config: autocomplete: {   maxHeight: undefined }
maxlength	Same as native maxlength, plus character counter	number | string	-
menuTag	Menu tag name	DynamicComponent	-	From config: autocomplete: {   menuTag: "div" }
mobileModal	Dropdown content (items) are shown into a modal on mobile	boolean	-	From config: autocomplete: {   mobileModal: false }
v-model	The selected option value, use v-model to make it two-way binding	string|number|object	-
openOnFocus	Open dropdown list on focus	boolean	-	From config: autocomplete: {   openOnFocus: false }
options	Autocomplete options	OptionsPropWithGroups<unknown>	-
override	Override existing theme classes completely	boolean	-
placeholder	Input placeholder	string	-
position	Position of the dropdown	"auto" | "bottom" | "top"	auto, top, bottom	From config: autocomplete: {   position: "auto" }
rounded	Makes the element rounded	boolean	-	false
selectOnClose	Trigger the select event for focused option when drodpown got closed	boolean	-	false
selectableFooter	Allows the footer in the autocomplete to be selectable	boolean	-	false
selectableHeader	Allows the header in the autocomplete to be selectable	boolean	-	false
size	Size of the input control	string	small, medium, large	From config: autocomplete: {   size: undefined }
statusIcon	Show status icon using field and variant prop	boolean	-	From config: {   statusIcon: true }
teleport	Append the component to another part of the DOM. Set true to append the component to the body. In addition, any CSS selector string or an actual DOM node can be used.	boolean | object | string	-	From config: autocomplete: {   teleport: false }
type	Input type	string	-	"text"
useHtml5Validation	Enable HTML 5 native validation	boolean	-	From config: {   useHtml5Validation: true }

Events

Event name	Properties	Description
update:model-value	value T - updated modelValue prop	modelValue prop two-way binding
update:input	value string - updated input prop	input prop two-way binding
update:active	value boolean - updated active prop	active prop two-way binding
input	value string - input value event Event - native event	on input change event
select	value T - selected value	selected element changed event
select-header		header is selected
select-footer		footer is selected
focus	event Event - native event	on input focus event
blur	event Event - native event	on input blur event
invalid	event Event - native event	on input invalid event
icon-click	event Event - native event	on icon click event
icon-right-click	event Event - native event	on icon right click event
scroll-start		the list inside the dropdown reached the start
scroll-end		the list inside the dropdown reached it's end

Slots

Name	Description	Bindings
header	Define an additional header
group	Override the option group	group object - options group index number - option index
default	Override the select option	option object - option object value unknown - option value index number - option index
empty	Define content for empty state
footer	Define an additional footer

Class Inspector

Classes applied to the element:

How does the Class props 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.
itemClass	Class of the menu items.
itemGroupTitleClass	Class of the menu items group title.
itemEmptyClass	Class of the empty menu placeholder item.
itemHeaderClass	Class of the menu header item.
itemFooterClass	Class of the menu footer item.
inputClasses	Classes to apply on the internal input component. More details here.

Sass variables

Current theme ➜ Oruga

SASS Variable	Default
$autocomplete-item-hover-background-color	#f5f5f5

See ➜ 📄 Full scss file

Current theme ➜ Bulma

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

Current theme ➜ Bootstrap

SASS Variable	Default
$autocomplete-menu-max-height	200px

See ➜ 📄 Full scss file