Dropdown
The Dropdown component is highly versatile and can be used in various ways, such as for displaying lists as contextual overlays, as a quick menu, or as a selectable list of content options.
Unlike native select elements, the dropdown input allows you to customize both its appearance and behavior. The component implements both the W3C ARIA APG Combobox Pattern as well as the W3C ARIA APG Menu Button Pattern, depending on whether the options are selectable.
Examples
Base (Menu)
By default the dropdown will be a simple unselectable menu using the ARIA: menu role . A menu generally represents a list of actions or functions that the user can invoke.
When a user clicks an option in a menu that has been opened, the menu usually closes. This can be changed with the keepOpen property. When a menu opens, keyboard focus can be placed on the first menu item using the keepFirst property.
Triggers
The trigger can be defined by placing any element in the trigger template slot. To open the dropdown, the component can detect several different interaction variants, such as openOnHover or openOnContextmenu to only open on right click instead of left click. By default, only openOnClick is set.
The action that close the component can also be customised using the closeOnOutside and closeOnScroll properties.
Adding the teleport prop will move the dropdown menu to the referenced DOM location instead.
Options
Instead of using the <o-dropdown-item> component directly inside the default template slot, an options prop can be defined, which can be used to specify the options programmatically. It accepts several different value formats:
- An array of primitives
['A', 'B', 'C'] - An object literal with key-value pairs
{ a: 'A', b: 'B', c: 'C' } - An array of objects where each object represent an item
- An array of grouped items where each group object has its own
optionsproperty
TypeScript
The options property type is defined by the DropdownOptions type.
Array of primitives
The simplest way to provide options is an array of primitives like strings or numbers, where the primitive will be used for both the string casted label representation and the value of the option.
Key-Value pair object
You may also provide the options prop where the keys are values and the values of each property are the labels.
Array of objects
The most flexible way to define options is to provide an array of objects. The object has the same properties as the <o-dropdown-item> component.
Grouped options
You can also use the array of objects syntax to create grouped options, wrapping each group of options in an object with a label and an options property. The object has the same properties as the <o-dropdown-item> component.
Selectable (Combobox)
The component can be configured to have the options as a selectable list by adding the selectable property. This applies the ARIA: combobox role to the root element and changes the menu to an ARIA: listbox role . The combobox role identifies an element as either an input or a button that controls another element, that can dynamically pop up to help the user set a value.
By default only one option can be selected and the selected option will be refereced by the modelValue property. Adding the multiple property will change the modelValue to an array of selected options.
Scrollable
When having to many options, consider adding the scrollable property, which allows the options container to remain at a fixed height. The max-height property can be used to define the max container height.
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 properties.
Position
The direction in which the dropdown menu opens can be changed by the position property. By default, the direction is automatically calculated from the distance to the edges of the window. Adding the teleport prop additionally will move the dropdown menu to the referenced DOM location instead.
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: { |
| ariaLabel | Accessibility aria-label to be passed to the trigger element - usefull if selectable | string | - | |
| 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: { |
| closeOnOutside | Close Dropdown when clicked outside | boolean | - | From config: dropdown: { |
| closeOnScroll | Close Dropdown when page get scrolled | boolean | - | From config: dropdown: { |
| 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: { |
| disabled | Interaction is disabled | boolean | - | false |
| expanded | Dropdown will be expanded (full-width) | boolean | - | false |
deprecated - since 0.13.0, use the OListbox component instead | boolean | - | false | |
| itemTag | Dropdown item tag name | DynamicComponent | - | From config: dropdown: { |
| keepFirst | The first option will always be pre-selected (easier to just hit enter or tab) | boolean | - | From config: dropdown: { |
| keepOpen | Keep dropdown list open when item get selected | boolean | - | From config: dropdown: { |
| label | Trigger label, unnecessary when trigger slot is used | string | - | |
| labelledby | Ensures that each input has an accessible name. | string | - | |
| maxHeight | Max height of dropdown content | Numberish | - | From config: dropdown: { |
| menuId | HTML element Id of the dropdown menu element | string | - | useId() |
| menuTag | Dropdown menu tag name | DynamicComponent | - | From config: dropdown: { |
| mobileBreakpoint | Mobile breakpoint as max-width value | string | - | From config: dropdown: { |
| mobileModal | Dropdown content (items) are shown into a modal on mobile | boolean | - | From config: dropdown: { |
| v-model | The selected option value, use v-model to make it two-way binding | ValueType<unknown, IsMultiple> | - | |
| multiple | Allows multiple selections - converts the modelValue into an array | IsMultiple | - | |
| openOnClick | Show when clicked on the trigger | boolean | - | From config: tooltip: { |
| openOnContextmenu | Show when right clicked on the trigger | boolean | - | From config: tooltip: { |
| openOnFocus | Show when trigger get focused | boolean | - | From config: tooltip: { |
| openOnHover | Show when hover over the trigger | boolean | - | From config: tooltip: { |
| options | Dropdown options, unnecessary when default slot is used | DropdownOptions<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: { |
| scrollable | Menu content will be scrollable | boolean | - | false |
| selectOnClose | Select current focused item when closed | boolean | - | From config: dropdown: { |
| selectOnFocus | Select current focused item when focused | boolean | - | From config: dropdown: { |
| 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: { |
| triggerTag | Dropdown trigger tag name | DynamicComponent | - | From config: dropdown: { |
Events
| Event name | Properties | Description |
|---|---|---|
| update:model-value | value unknown | unknown[] - updated modelValue prop | modelValue prop two-way binding |
| update:active | value boolean - updated active prop | active prop two-way binding |
| select | value unknown - selected value | on select event - fired before update:modelValue |
| change | value unknown | unknown[] - selected value | |
| open | event Event - native event | on active state changes to true |
| close | event Event - native event | on active state changes to false |
| 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 statevalue unknown | unknown[] - the selected valuetoggle (event: Event): void - toggle dropdown active state |
| before | Define extra o-dropdown-item components here, even if you have some options defined by prop | toggle (): void - toggle dropdown active state |
| default | Define the dropdown items here | toggle (): void - toggle dropdown active state |
| group | Override the option group | group object - options group item |
| option | Override the label, default is label prop | option object - option item |
| empty | Define the content to show if the list is empty | toggle (): void - toggle dropdown active state |
| after | Define extra o-dropdown-item components here, even if you have some options defined by prop | toggle (): void - toggle dropdown active state |
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 | - | |
| value | Item value (it will be used as the v-model of the wrapper component) - default is an uuid | string|number|object | - | useId() |
Events
| Event name | Properties | Description |
|---|---|---|
| click | value unknown - value prop dataevent event - native event | onclick event |
Slots
| Name | Description | Bindings |
|---|---|---|
| default | Override the label, default is label prop |
Class Inspector
| 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 | ||
| 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 | ||
| hoverableClass | Class of the root element when trigger is hoverable. | openOnHover | ||
| positionClass | Class of the root element with postion. | position | auto | |
| triggerClass | Class of the trigger element. | |||
| overlayClass | Class of the overlay element when shown as modal. | mobileModal | ||
| menuClass | Class of the menu element. | |||
| menuActiveClass | Class of the menu element when active or inline. | inline | ||
| menuPositionClass | Class of the menu element with position. | position | auto | |
| ▷ 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 | h.useVar("control-disabled-opacity") |
| $dropdown-menu-zindex | map.get(vars.$zindex, "dropdown") |
| $dropdown-menu-spacer | 0px |
| $dropdown-menu-padding | h.useVar("control-spacer") 0 |
| $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-background-color | h.useVar("control-brackground-color") |
| $dropdown-menu-border-color | h.useVar("control-border-color") |
| $dropdown-menu-border-style | solid |
| $dropdown-menu-border-width | h.useVar("control-border-width") |
| $dropdown-menu-border-radius | h.useVar("border-radius") |
| $dropdown-item-padding | 0.25rem 1rem |
| $dropdown-item-color | h.useVar("font-color") |
| $dropdown-item-font-size | h.useVar("font-size") |
| $dropdown-item-font-weight | h.useVar("font-weight") |
| $dropdown-item-line-height | h.useVar("line-height") |
| $dropdown-item-background-color | transparent |
| $dropdown-item-active-color | h.useVar("primary-invert") |
| $dropdown-item-active-background-color | h.useVar("primary") |
| $dropdown-item-hover-background-color | h.useVar("grey-lighter") |
| $dropdown-item-hover-color | h.useVar("font-color") |
| $dropdown-modal-zindex | map.get(vars.$zindex, "modal") |
| $dropdown-modal-max-height | min(50vh, calc(100vh - 160px)) |
| $dropdown-modal-max-width | min(50vw, calc(100vw - 160px)) |
| $dropdown-modal-min-width | min(80vw, 400px) |
| $dropdown-overlay-background-color | h.useVar( "overlay-background-color") |
| $dropdown-overlay-zindex | map.get(vars.$zindex, "overlay") |
See ➜ 📄 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 ➜ 📄 SCSS file
