Skip to content

Dropdown.md

Latest commit

 

History

History
221 lines (170 loc) · 35.9 KB

Dropdown.md

File metadata and controls

221 lines (170 loc) · 35.9 KB
sidebarDepth 2

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

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 -
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 Interaction is disabled boolean - false
expanded Dropdown will be expanded (full-width) boolean - false
inline
deprecated - since 0.13.0, use the OListbox component instead
Menu content (items) are shown inline, trigger is removed
 boolean - false
itemTag Dropdown item tag name DynamicComponent -
From config:
dropdown: {
  itemTag: "div"
}
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 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: {
  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, 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: {
  openOnClick: true
}
openOnContextmenu Show when right clicked on the trigger boolean -
From config:
tooltip: {
  openOnContextmenu: false
}
openOnFocus Show when trigger get focused boolean -
From config:
tooltip: {
  openOnFocus: false
}
openOnHover Show when hover over the trigger boolean -
From config:
tooltip: {
  openOnHover: false
}
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: {
  position: "bottom-left"
}
scrollable Menu 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"
}

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 state
value unknown | unknown[] - the selected value
toggle (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 data
event event - native event		 onclick event

Slots

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

Class Inspector

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

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 ➜ 📄 SCSS file