Skip to content

Dropdown.md

Latest commit

 

History

History
207 lines (157 loc) · 32.2 KB

Dropdown.md

File metadata and controls

207 lines (157 loc) · 32.2 KB
sidebarDepth 2

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

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
}
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"
}
scroll Use clip to remove the body scrollbar, keep to have a non scrollable scrollbar to avoid shifting background,
but will set body to position fixed, might break some layouts.		 "clip" | "keep" keep, clip
From config:
dropdown: {
  scroll: "keep"
}
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 () =&gt; void - toggle dropdown active state
default Place dropdown items here active boolean - dropdown active state

toggle () =&gt; 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

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-mobile-breakpoint vars.$desktop
$dropdown-background-background-color hsla( #{css.getVar("scheme-h")}, #{css.getVar("scheme-s")}, #{css.getVar("scheme-invert-l")}, 0.86)
$dropdown-disabled-opacity 0.5
$dropdown-gap 0px
$dropdown-z 40

See ➜ 📄 Full scss file

Current theme ➜ Bootstrap

SASS Variable Default
$dropdown-modal-menu-zindex $zindex-modal
$dropdown-modal-backdrop-zindex $zindex-modal-backdrop

See ➜ 📄 Full scss file