Dropdown

The Dropdown component is very versatile and can be used as contextual overlays for displaying lists as a quick menu or even toggleable to allow users to select a value from a list of content options. Unlike native select elements, the dropdown input allows you to customize both its appearance and behavior. The component implements the W3C ARIA APG Combobox Pattern.

Examples

Base

The dropdown will be a simple unselectable menu list by default.

Show code

HTML

<section class="odocs-spaced">
    <o-dropdown>
        <template #trigger="{ active }">
            <o-button
                variant="primary"
                label="Click me!"
                :icon-right="active ? 'caret-up' : 'caret-down'" />
        </template>

        <o-dropdown-item label="Action" />
        <o-dropdown-item label="Another action" />
        <o-dropdown-item label="Something else" />
    </o-dropdown>
</section>

Triggers

The component accepts several different trigger variants, such as open on hover or open only on right click instead of left click.

Adding the teleport prop will move the dropdown menu to the referenced DOM location instead.

Show code

HTML

<section class="odocs-spaced">
    <p>
        <o-dropdown>
            <template #trigger="{ active }">
                <o-button
                    variant="primary"
                    label="Default"
                    :icon-right="active ? 'caret-up' : 'caret-down'" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown :triggers="['hover']">
            <template #trigger="{ active }">
                <o-button
                    variant="info"
                    label="Hover"
                    :icon-right="active ? 'caret-up' : 'caret-down'" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown :triggers="['contextmenu']">
            <template #trigger>
                <o-button label="Right click" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown disabled>
            <template #trigger="{ active }">
                <o-button
                    label="Disabled"
                    disabled
                    :icon-right="active ? 'caret-up' : 'caret-down'" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown>
            <template #trigger>
                <div role="button" tabindex="0">
                    Custom
                    <o-icon variant="success" icon="caret-down" />
                </div>
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown teleport>
            <template #trigger>
                <o-button label="Append to body" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>
    </p>
    <br />
    <p>
        <o-field grouped>
            <o-dropdown v-model:active="active" :triggers="[]">
                <template #trigger> Click the button beside! </template>

                <o-dropdown-item label="Action" />
                <o-dropdown-item label="Another action" />
                <o-dropdown-item label="Something else" />
            </o-dropdown>

            <o-button
                label="Open / Close"
                variant="primary"
                @click="active = !active" />
        </o-field>
    </p>
</section>

JS

import { ref } from "vue";

const active = ref(false);

Options

Instead of using the <o-dropdown-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-dropdown
                v-model="selected"
                :options="options"
                selectable
                aria-label="options example">
                <template #trigger="{ active }">
                    <o-button
                        variant="primary"
                        label="Click me!"
                        :icon-right="active ? 'caret-up' : 'caret-down'" />
                </template>
            </o-dropdown>

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

        <o-field label="Grouped Options">
            <o-dropdown
                v-model="groupSelected"
                :options="groupOptions"
                selectable
                scrollable
                aria-label="group example">
                <template #trigger="{ active }">
                    <o-button
                        variant="primary"
                        label="Click me!"
                        :icon-right="active ? 'caret-up' : 'caret-down'" />
                </template>
            </o-dropdown>

            <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: "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<string>();

Selectable

Components with the prop selectable will have options as a selectable list.

Adding the multiple prop will change the modelValue prop to an array of selected options.

Show code

HTML

<section class="odocs-spaced">
    <o-field grouped>
        <o-switch v-model="keepFirst">Keep first</o-switch>
        <o-switch v-model="keepOpen">Keep open</o-switch>
        <o-switch v-model="selectOnClose">Select on close</o-switch>
        <o-switch v-model="selectOnFocus">Select on focus</o-switch>
    </o-field>

    <o-field grouped>
        <o-field label="Single Selection">
            <o-dropdown
                v-model:model-value="selectedOption"
                selectable
                :keep-open="keepOpen"
                :keep-first="keepFirst"
                :select-on-close="selectOnClose"
                :select-on-focus="selectOnFocus">
                <template #trigger="{ value }">
                    <o-button
                        variant="primary"
                        type="button"
                        icon-right="caret-down">
                        Selected ({{ value }})
                    </o-button>
                </template>

                <o-dropdown-item value="option1" label="Option 1" />
                <o-dropdown-item value="option2" label="Option 2" />
                <o-dropdown-item value="option3" label="Option 3" />
            </o-dropdown>

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

        <o-field label="Multiple Selection">
            <o-dropdown
                v-model:model-value="selectedOptions"
                selectable
                multiple
                :keep-open="keepOpen"
                :keep-first="keepFirst"
                :select-on-close="selectOnClose"
                :select-on-focus="selectOnFocus">
                <template #trigger>
                    <o-button
                        variant="primary"
                        type="button"
                        icon-right="caret-down">
                        Selected ({{ selectedOptions.length }})
                    </o-button>
                </template>

                <o-dropdown-item value="option1" label="Option 1" />
                <o-dropdown-item value="option2" label="Option 2" />
                <o-dropdown-item value="option3" label="Option 3" />
            </o-dropdown>

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

JS

import { ref } from "vue";

const selectedOption = ref();

const selectedOptions = ref([]);

const keepFirst = ref(false);
const keepOpen = ref(true);
const selectOnClose = ref(false);
const selectOnFocus = ref(false);

Inline

Components with the inline prop set will render the options list directly, and will not have a trigger element rendered.

Show code

HTML

<section class="odocs-spaced">
    <o-dropdown
        v-model="selectedOption"
        inline
        selectable
        aria-label="inline example">
        <template #trigger>
            <o-button label="Inline" />
        </template>

        <o-dropdown-item :value="1" label="Action " />
        <o-dropdown-item :value="2" label="Another action " />
        <o-dropdown-item :value="3" label="Something else " />
    </o-dropdown>

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

JS

import { ref } from "vue";

const selectedOption = ref();

Modal

The content can be opened in an modal mode either for mobile or desktop only, or for both, by adding the mobile-modal and desktop-modal props.

Show code

HTML

<section class="odocs-spaced">
    <o-dropdown mobile-modal desktop-modal aria-label="modal example">
        <template #trigger>
            <o-button variant="primary" label="Click to open modal!" />
        </template>

        <o-dropdown-item label="Action" />
        <o-dropdown-item label="Another action" />
        <o-dropdown-item label="Something else" />
    </o-dropdown>
</section>

Scrollable

When having to many options, consider adding the scrollable prop, which allows the menu to remain at a fixed height.

Show code

HTML

<section>
    <o-field>
        <o-switch v-model="isScrollable" label="Scrollable" />
    </o-field>

    <o-dropdown
        v-model="currentMenu"
        :scrollable="isScrollable"
        :max-height="maxHeight"
        check-scroll>
        <template #trigger>
            <o-button
                variant="primary"
                type="button"
                :label="currentMenu.text"
                :icon-left="currentMenu.icon"
                icon-right="caret-down" />
        </template>

        <o-dropdown-item
            v-for="(menu, index) in menus"
            :key="index"
            :value="menu">
            <div class="media">
                <o-icon class="media-left" :icon="menu.icon" />
                <div class="media-content">{{ menu.text }}</div>
            </div>
        </o-dropdown-item>
    </o-dropdown>
</section>

JS

import { ref } from "vue";

const maxHeight = 200;
const menus = [
    { icon: "users", text: "People" },
    { icon: "box", text: "Orders" },
    { icon: "credit-card", text: "Payments" },
    { icon: "dolly", text: "Logistics" },
    { icon: "business-time", text: "Jobs" },
    { icon: "shopping-cart", text: "Cart" },
    { icon: "cog", text: "Configuration" },
];

const isScrollable = ref(true);
const currentMenu = ref({ icon: "users", text: "People" });

SCSS

.media {
    align-items: flex-start;
    display: flex;
    text-align: left;
}
.media-content {
    flex-basis: auto;
    flex-grow: 1;
    flex-shrink: 1;
    text-align: left;
    overflow-y: hidden;
    overflow-x: auto;
}
.media-left {
    margin-right: 1rem;
    flex-basis: auto;
    flex-grow: 0;
    flex-shrink: 0;
}

Position

The direction in which the dropdown menu opens can be defined by the position prop. By default, the direction is automatically calculated from the distance to the edge of the window. Adding the teleport prop additionally will move the dropdown menu to the referenced DOM location instead.

Show code

HTML

<section class="odocs-spaced">
    <o-field>
        <o-switch v-model="teleport" label="teleport" />
    </o-field>

    <p>
        <o-dropdown position="auto" expanded :teleport="teleport">
            <template #trigger>
                <o-button
                    variant="primary"
                    label="Position Auto"
                    expanded />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>
    </p>

    <p>
        <o-dropdown position="right" :teleport="teleport">
            <template #trigger>
                <o-button label="Append to right" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown position="left" :teleport="teleport">
            <template #trigger>
                <o-button label="Append to left" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown position="top" :teleport="teleport">
            <template #trigger>
                <o-button label="Append to top" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown position="bottom" :teleport="teleport">
            <template #trigger>
                <o-button label="Append to bottom" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>
    </p>

    <p>
        <o-dropdown position="top-right" :teleport="teleport">
            <template #trigger>
                <o-button label="Append to top-right" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown position="top-left" :teleport="teleport">
            <template #trigger>
                <o-button label="Append to top-left" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown position="bottom-right" :teleport="teleport">
            <template #trigger>
                <o-button label="Append to bottom-right" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>

        <o-dropdown position="bottom-left" :teleport="teleport">
            <template #trigger>
                <o-button label="Append to bottom-left" />
            </template>

            <o-dropdown-item label="Action" />
            <o-dropdown-item label="Another action" />
            <o-dropdown-item label="Something else" />
        </o-dropdown>
    </p>
</section>

JS

import { ref } from "vue";

const teleport = ref(false);

Dropdown component

Dropdowns are very versatile, can used as a quick menu or even like a select for discoverable content.

<o-dropdown></o-dropdown>

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	Custom animation (transition name)	string	-	From config: dropdown: {   animation: "fade" }
ariaLabel	Accessibility aria-label to be passed to the trigger element - usefull if selectable	string	-
checkScroll	Makes the component check if menu reached scroll start or end and emit scroll events	boolean	-	From config: dropdown: {   checkScroll: false }
clipScroll	Set true to remove the body scrollbar. When false, a non-scrollable scrollbar will be kept to avoid moving the background, but will set the body to a fixed position, which may break some layouts.	boolean	-	From config: dropdown: {   clipScroll: false }
closeOnOutside	Close Dropdown when clicked outside	boolean	-	From config: dropdown: {   closeOnOutside: true }
closeOnScroll	Close Dropdown when page get scrolled	boolean	-	From config: dropdown: {   closeOnScroll: false }
delay	Dropdown delay before it appears (number in ms)	number	-
desktopModal	Dropdown content (items) are shown into a modal on desktop	boolean	-	From config: dropdown: {   desktopModal: false }
disabled	Dropdown is disabled	boolean	-	false
expanded	Dropdown will be expanded (full-width)	boolean	-	false
inline	Dropdown content (items) are shown inline, trigger is removed	boolean	-	false
keepFirst	The first option will always be pre-selected (easier to just hit enter or tab)	boolean	-	From config: dropdown: {   keepFirst: false }
keepOpen	Keep dropdown list open when item get selected	boolean	-	From config: dropdown: {   keepOpen: false }
label	Trigger label, unnecessary when trgger slot is used	string	-
labelledby	Ensures that each input has an accessible name.	string	-
maxHeight	Max height of dropdown content	number | string	-	From config: dropdown: {   maxHeight: 200 }
menuId	HTML element Id of the dropdown menu element	string	-	useId()
menuTag	Dropdown menu tag name	DynamicComponent	-	From config: dropdown: {   menuTag: "div" }
mobileBreakpoint	Mobile breakpoint as max-width value	string	-	From config: dropdown: {   mobileBreakpoint: undefined }
mobileModal	Dropdown content (items) are shown into a modal on mobile	boolean	-	From config: dropdown: {   mobileModal: true }
v-model	The selected option value	unknown	-
multiple	Allows multiple selections - converts the modelValue into an array	boolean	-
options	Dropdown options, unnecessary when default slot is used	OptionsPropWithGroups<unknown>	-
override	Override existing theme classes completely	boolean	-
position	Position of the dropdown relative to the trigger	"auto" | "bottom-left" | "bottom-right" | "bottom" | "left" | "right" | "top-left" | "top-right" | "top"	auto, top, bottom, left, right, top-right, top-left, bottom-left, bottom-right	From config: dropdown: {   position: "bottom-left" }
scrollable	Dropdown content will be scrollable	boolean	-	false
selectOnClose	Select current focused item when closed	boolean	-	From config: dropdown: {   selectOnClose: false }
selectOnFocus	Select current focused item when focused	boolean	-	From config: dropdown: {   selectOnFocus: false }
selectable	Enables item selection	boolean	-	false
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: dropdown: {   teleport: false }
triggerTag	Dropdown trigger tag name	DynamicComponent	-	From config: dropdown: {   triggerTag: "div" }
triggers	Dropdown will be triggered by any events	("click" | "contextmenu" | "focus" | "keydown" | "hover")[]	click, hover, contextmenu, focus	From config: dropdown: {   triggers: ["click"] }

Events

Event name	Properties	Description
update:model-value	value T | T[] - updated modelValue prop	modelValue prop two-way binding
update:active	value boolean - updated active prop	active prop two-way binding
select	value T - selected value	on select event - fired before update:modelValue
change	value T | T[] - selected value
open	method string - open method event Event - native event	on open event
close	method string - close method event Event - native event	on close 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
trigger	Override the trigger element, default is label prop	active boolean - dropdown active state value T | T[] - the selected value toggle () => void - toggle dropdown active state
default	Place dropdown items here	active boolean - dropdown active state toggle () => void - toggle dropdown active state
before	Place extra o-dropdown-item components here, even if you have some options defined by prop
group	Override the option group	group object - options group index number - option index
after	Place extra o-dropdown-item components here, even if you have some options defined by prop

DropdownItem component

An option item used by the dropdown component.

<o-dropdown-item></o-dropdown-item>

Props

Prop name	Description	Type	Values	Default
clickable	Item is clickable and emit an event	boolean	-	true
disabled	Item is disabled	boolean	-	false
hidden	Define whether the item is visible or not	boolean	-	false
label	Item label, unnecessary when default slot is used	string	-
override	Override existing theme classes completely	boolean	-
tag	Dropdown item tag name	DynamicComponent	-	From config: dropdown: {   itemTag: "div" }
value	Item value (it will be used as v-model of wrapper component) - default is an uuid	string|number|object	-

Events

Event name	Properties	Description
click	value string | number | object - value prop data event event - Native Event	onclick event

Slots

Name	Description	Bindings
default	Override the label, default is label prop

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.
mobileClass	Class of the root element when on mobile. 👉 Switch to mobile view to see it in action!
modalClass	Class of the root element when shown as modal.	mobileModal desktopModal
teleportClass	Class of the root element when teleported.	teleport
disabledClass	Class of the root element when disabled.	disabled
inlineClass	Class of the root element when inlined.	inline
expandedClass	Class of the root element when expanded.	expanded
activeClass	Class of the root element when active or inline.	active inline
hoverableClass	Class of the root element when trigger is hoverable.	triggers
positionClass	Class of the root element with postion.	position	auto top bottom left right top-right top-left bottom-left bottom-right auto top bottom left right top-right top-left bottom-left bottom-right
triggerClass	Class of the trigger element.
overlayClass	Class of the overlay element when shown as modal.	mobileModal desktopModal
menuClass	Class of the menu element.
menuActiveClass	Class of the menu element when active or inline.	inline active
menuPositionClass	Class of the menu element with position.	position	auto top bottom left right top-right top-left bottom-left bottom-right auto top bottom left right top-right top-left bottom-left bottom-right
▷ itemClass	Class of the item element.
▷ itemSelectedClass	Class of the item element when selected.
▷ itemDisabledClass	Class of the item element when disabled.	disabled
▷ itemClickableClass	Class of the item element when clickable.	clickable
▷ itemFocusedClass	Class of the item element when focused.
scrollClipClass	Class of the body when is open and scroll is clipped.	clipScroll
scrollKeepClass	Class of the body when is open and scroll is keeped.	clipScroll

Sass variables

Current theme ➜ Oruga

SASS Variable	Default
$dropdown-disabled-opacity	var(--#{$prefix}base-disabled-opacity)
$dropdown-item-active-background-color	var(--#{$prefix}primary)
$dropdown-item-active-color	var(--#{$prefix}primary-invert)
$dropdown-item-color	#000000
$dropdown-item-disabled-opacity	var( --#{$prefix}base-disabled-opacity)
$dropdown-item-font-size	var(--#{$prefix}base-font-size)
$dropdown-item-hover-background-color	#f5f5f5
$dropdown-item-hover-color	#000000
$dropdown-item-line-height	var(--#{$prefix}base-line-height)
$dropdown-item-padding	0.375rem 1rem
$dropdown-item-font-weight	400
$dropdown-menu-background	#ffffff
$dropdown-menu-border-radius	var(--#{$prefix}base-border-radius)
$dropdown-menu-box-shadow	0 0.5em 1em -0.125em rgba(10, 10, 10, 0.1), 0 0 0 1px rgba(10, 10, 10, 0.02)
$dropdown-menu-spacer	0px
$dropdown-menu-margin	0
$dropdown-menu-padding	0.5rem 0 0.5rem 0
$dropdown-menu-width	12rem
$dropdown-menu-zindex	50
$dropdown-mobile-max-height	calc(100vh - 120px)
$dropdown-mobile-max-width	460px
$dropdown-mobile-overlay-color	rgba(#000000, 0.86)
$dropdown-mobile-overlay-zindex	55
$dropdown-mobile-width	calc(100vw - 40px)
$dropdown-mobile-zindex	60

See ➜ 📄 Full scss file

Current theme ➜ Bulma

SASS Variable	Default
$dropdown-content-max-height	200px
$dropdown-disabled-opacity	0.5
$dropdown-gap	0px
$dropdown-z	40
$dropdown-mobile-breakpoint	iv.$desktop
$dropdown-background-background-color	hsla( #{css.getVar("scheme-h")}, #{css.getVar("scheme-s")}, #{css.getVar("scheme-invert-l")}, 0.86)
$dropdown-modal-width	75%
$dropdown-modal-min-width	25%
$dropdown-modal-max-width	calc(100vw - 40px)

See ➜ 📄 Full scss file

Current theme ➜ Bootstrap

SASS Variable	Default
$dropdown-modal-menu-zindex	$zindex-modal
$dropdown-modal-backdrop-zindex	$zindex-modal-backdrop
$dropdown-modal-width	75%
$dropdown-modal-min-width	25%
$dropdown-modal-max-width	calc(100vw - 40px)

See ➜ 📄 Full scss file