Usage
A dropdown menu is a compact way of displaying multiple choices. It appears upon interaction with an element (such as an icon or button) or when users perform a specific action.
Placement
Dropdown menus are positioned relative to both the element that generates them and the edges of the screen or browser. They can appear in front of, beside, above, or below the element that generates them.
Default placement
A dropdown menu is typically positioned below the element that generates it.
Menu alignment
The dropdown menu can either be left aligned (default), centered or right aligned with respect to the element above it.
Dropup, right or left
A dropdown menu can also be positioned above, to the left or right of the element that generates it.
Styling options
The dropdown trigger button can have various styling options.
Dropdown color variants
The dropdown toggle button can have one of the standard WUI contextual variants applied.
Split button color variant
The default left split button typically has the same variant as the toggle button. But the split button can also have its own variant.
Menu content
Headers
Add a header to label sections of actions in any dropdown menu.
Groups
Group a set of dropdown sub components with an optional associated header.
Dividers
Separate groups of related menu items with a divider.
Text
Place any freeform text within a dropdown menu with text and use spacing utilities. Note that you’ll likely need additional sizing styles to constrain the menu width.
Forms
Put a form within a dropdown menu, or make it into a dropdown menu, and use margin or padding utilities to give it the negative space you require.
Description
Dropdowns are toggleable, contextual overlays for displaying lists of links and actions in a dropdown menu format.
<wui-dropdown> (or known by its shorter alias of <wui-dd>) components are toggleable, contextual overlays for displaying lists of links and more. They're toggled by clicking (or pressing space or enter when focused), not by hovering; this is an intentional design decision.
<div>
<wui-dropdown id="dropdown-1" text="Dropdown Button" class="m-10">
<wui-dropdown-item>First Action</wui-dropdown-item>
<wui-dropdown-item>Second Action</wui-dropdown-item>
<wui-dropdown-item>Third Action</wui-dropdown-item>
<wui-dropdown-divider></wui-dropdown-divider>
<wui-dropdown-item active>Active action</wui-dropdown-item>
<wui-dropdown-item disabled>Disabled action</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown.vue -->
Button content
You can customize the text of the dropdown button by using either the text prop (shown in previous examples), or use the button-content slot instead of the text prop. The button-content slot allows you to use basic HTML and icons in the button content.
If both the prop text and slot button-content are present, the slot button-content will take precedence.
<div>
<wui-dropdown text="Button text via Prop">
<wui-dropdown-item href="#">An item</wui-dropdown-item>
<wui-dropdown-item href="#">Another item</wui-dropdown-item>
</wui-dropdown>
<wui-dropdown>
<template #button-content>
Custom <strong>Content</strong> with <em>HTML</em> via Slot
</template>
<wui-dropdown-item href="#">An item</wui-dropdown-item>
<wui-dropdown-item href="#">Another item</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-button-content.vue -->
Positioning
Dropdown supports various positioning such as left and right aligned, dropdown and dropup, and supports auto-flipping (dropdown to dropup, and vice-versa) when the menu would overflow off of the visible screen area.
Menu alignment
The dropdown menu can either be left aligned (default), centered or right aligned with respect to the button above it. To have the dropdown centered, set the centered prop. To have the dropdown aligned on the right, set the right prop.
<div>
<wui-dropdown
id="dropdown-left"
text="Left align"
variant="primary"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
<wui-dropdown
id="dropdown-centered"
centered
text="Centered"
variant="primary"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#"
>Something else here with longer text</wui-dropdown-item
>
</wui-dropdown>
<wui-dropdown
id="dropdown-right"
right
text="Right align"
variant="primary"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-right.vue -->
Dropup
Turn your dropdown menu into a drop-up menu by setting the dropup prop.
<div>
<wui-dropdown
id="dropdown-dropup"
dropup
text="Drop-Up"
variant="primary"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
<wui-dropdown
id="dropdown-dropup-centered"
dropup
centered
text="Drop-Up Centered"
variant="primary"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#"
>Something else here with longer text</wui-dropdown-item
>
</wui-dropdown>
</div>
<!-- wui-dropdown-dropup.vue -->
Drop right or left
Turn your dropdown menu into a drop-right menu by setting the dropright prop. Or, turn it into a drop-left menu by setting the dropleft right prop to true.
dropright takes precedence over dropleft. Neither dropright or dropleft have any effect if dropup is set.
<div>
<wui-dropdown
id="dropdown-dropright"
dropright
text="Drop-Right"
variant="primary"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
<wui-dropdown
id="dropdown-dropleft"
dropleft
text="Drop-Left"
variant="primary"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-dropright-dropleft.vue -->
Auto "flipping"
By default, dropdowns may flip to the top, or to the bottom, based on their current position in the viewport. To disable this auto-flip feature, set the no-flip prop.
Menu offset
Like to move your menu away from the toggle buttons a bit? Then use the offset prop to specify the number of pixels to push right (or left when negative) from the toggle button:
- Specified as a number of pixels: positive for right shift, negative for left shift.
- Specify the distance in CSS units (i.e.
0.3rem,4px,1.2em, etc.) passed as a string.
<div>
<wui-dropdown
id="dropdown-offset"
offset="25"
text="Offset Dropdown"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-offset.vue -->
Boundary constraint
By default, dropdowns are visually constrained to its scroll parent, which will suffice in most situations. However, if you place a dropdown inside an element that has overflow: scroll (or similar) set, the dropdown menu may - in some situations - get cut off. To get around this, you can set the fixed prop to true. The value is passed directly to @floating-ui's strategy configuration option.
Note: When fixed is true, the style position: fixed is applied to to the dropdown component's menu element in order to allow the menu to "break-out" of its scroll container. In some situations this may affect your layout or positioning of the dropdown trigger button. In these cases you may need to wrap your dropdown inside another element.
Advanced @floating-ui configuration
If you need some advanced @floating-ui configuration to make dropdowns behave to your needs, you can use the floating-ui-opts prop to pass down a custom configuration object which will be deeply merged with the WuiVue defaults.
Head to the @floating-ui docs to see all the configuration options.
Note: The props offset, fixed and no-flip may loose their effect when you overwrite the @floating-ui configuration.
Split button support
Create a split dropdown button, where the left button provides standard click event and link support, while the right hand side is the dropdown menu toggle button.
<div>
<wui-dropdown split text="Split Dropdown" class="m-10">
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here...</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-split.vue -->
Split button link support
The left split button defaults to an element of type <button> (a <wui-button> to be exact). To convert this button into a link or <router-link>, specify the href via the split-href prop or a router link to value via the split-to prop, while maintaining the look of a button.
<div>
<wui-dropdown split split-href="#foo/bar" text="Split Link" class="m-10">
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here...</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-split-link.vue -->
Split button type
The split button defaults to a button type of 'button'. You can specify an alternate type via the split-button-type prop. Supported values are: 'button', 'submit' and 'reset'.
If props split-to or split-href are set, the split-button-type prop will be ignored.
Styling options
Dropdowns support various props for styling the dropdown trigger button.
Sizing
Dropdowns work with trigger buttons of all sizes, including default and split dropdown buttons.
Set the size prop to either sm for small button(s), or lg for large button(s).
<div>
<div>
<wui-dropdown size="lg" text="Large" class="m-10">
<wui-dropdown-item-button>Action</wui-dropdown-item-button>
<wui-dropdown-item-button>Another action</wui-dropdown-item-button>
<wui-dropdown-item-button>Something else here</wui-dropdown-item-button>
</wui-dropdown>
<wui-dropdown size="lg" split text="Large Split" class="m-10">
<wui-dropdown-item-button>Action</wui-dropdown-item-button>
<wui-dropdown-item-button>Another action</wui-dropdown-item-button>
<wui-dropdown-item-button
>Something else here...</wui-dropdown-item-button
>
</wui-dropdown>
</div>
<div>
<wui-dropdown size="sm" text="Small" class="m-10">
<wui-dropdown-item-button>Action</wui-dropdown-item-button>
<wui-dropdown-item-button>Another action</wui-dropdown-item-button>
<wui-dropdown-item-button
>Something else here...</wui-dropdown-item-button
>
</wui-dropdown>
<wui-dropdown size="sm" split text="Small Split" class="m-10">
<wui-dropdown-item-button>Action</wui-dropdown-item-button>
<wui-dropdown-item-button>Another action</wui-dropdown-item-button>
<wui-dropdown-item-button
>Something else here...</wui-dropdown-item-button
>
</wui-dropdown>
</div>
</div>
<!-- wui-dropdown-sizes.vue -->
Note: changing the size of the button(s) does not affect the size of the menu items!
Dropdown color variants
The dropdown toggle button can have one of the standard WUI contextual variants applied by setting the prop variant to success, primary, info, danger, link, outline-dark, etc. (or custom variants, if defined). The default variant is default.
See the Variant Reference for a full list of built-in contextual variants.
<div>
<wui-dropdown text="Primary" variant="primary" class="m-10">
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
<wui-dropdown text="Success" variant="success" class="m-10">
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
<wui-dropdown text="Outline Danger" variant="outline-danger" class="m-10">
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-variants.vue -->
You can also apply arbitrary classes to the toggle button via the toggle-class prop. This prop accepts either a string or array of strings.
Split button color variant
By default the left split button uses the same variant as the toggle button. You can give the split button its own variant via the split-variant prop.
<div>
<wui-dropdown
split
split-variant="active"
variant="primary"
text="Split Variant Dropdown"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here...</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-split-variant.vue -->
Block level dropdowns
By default dropdowns act like buttons and are displayed inline. To create block level dropdowns (that span to the full width of a parent) set the block prop. Both, regular and split button dropdowns are supported.
<div>
<wui-dropdown
text="Block Level Dropdown"
block
variant="primary"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
<wui-dropdown
text="Block Level Split Dropdown"
block
split
split-variant="outline-primary"
variant="primary"
class="m-10"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here...</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-block.vue -->
If you want the dropdown menu to span to the full width of the parent container too, add the w-full utility class to the menu-class prop.
<div>
<wui-dropdown
text="Block Level Dropdown Menu"
block
variant="primary"
class="m-10"
menu-class="w-100"
>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-block-menu.vue -->
Dropdown sub-component color variants
Many of the supported dropdown sub-components provide a variant prop for controlling their text color.
Hidden caret
The dropdown can be created with the toggle's caret visually hidden by setting the no-caret prop to true. This is useful when the dropdown is to be displayed as an icon.
<div>
<wui-dropdown
size="lg"
variant="link"
toggle-class="text-decoration-none"
no-caret
>
<template #button-content>
🔍<span class="sr-only">Search</span>
</template>
<wui-dropdown-item href="#">Action</wui-dropdown-item>
<wui-dropdown-item href="#">Another action</wui-dropdown-item>
<wui-dropdown-item href="#">Something else here...</wui-dropdown-item>
</wui-dropdown>
</div>
<!-- wui-dropdown-hidden-caret.vue -->
Note: The caret will always be shown when using split mode.
Lazy dropdown
By default, <wui-dropdown> renders the menu contents in the DOM even when the menu is not shown. When there are a large number of dropdowns rendered on the same page, performance could be impacted due to larger overall memory utilization. You can instruct <wui-dropdown> to render the menu contents only when it is shown by setting the lazy prop to true.
Dropdown supported sub-components
The following components can be placed inside of your dropdowns. Using any other component or markup may break layout and/or keyboard navigation.
| Sub-component | Description | Aliases |
|---|---|---|
<wui-dropdown-item> | Action items that provide click, link, and <router-link>/<nuxt-link> functionality. Renders as an <a> element by default. | <wui-dd-item> |
<wui-dropdown-item-button> | An alternative to <wui-dropdown-item> that renders a menu item using a <button> element. | <wui-dropdown-item-btn>, <wui-dd-item-button>, <wui-dd-item-btn> |
<wui-dropdown-divider> | A divider / spacer which can be used to separate dropdown items. | <wui-dd-divider> |
<wui-dropdown-text> | Free flowing text content in a menu. | <wui-dd-text> |
<wui-dropdown-form> | For placing form controls within a dropdown menu. | <wui-dd-form> |
<wui-dropdown-group> | For grouping dropdown sub components with an optional header. | <wui-dd-group> |
<wui-dropdown-header> | A header item, used to help identify a group of dropdown items. | <wui-dd-header> |
Note: Nested sub-menus are not supported.
<wui-dropdown-item>
The <wui-dropdown-item> is typically used to create a navigation link inside your menu. Use either the href prop or the to prop (for router link support) to generate the appropriate navigation link. If neither href nor to are provided, a standard <a> link will be generated with an href of # (with an event handler that will prevent scroll to top behaviour by preventing the default link action).
Disabled the dropdown item by setting the disabled prop.
<wui-dropdown-item-button>
Historically dropdown menu contents had to be links (<wui-dropdown-item>), but that's no longer the case with Bootstrap v4. Now you can optionally create <button> elements in your dropdowns by using the <wui-dropdown-item-button> sub-component. <wui-dropdown-item-button> does not support the href or to props.
Disabled the dropdown item button by setting the disabled prop.
<div>
<wui-dropdown
id="dropdown-buttons"
text="Dropdown using buttons as menu items"
class="m-10"
>
<wui-dropdown-item-button>I'm a button</wui-dropdown-item-button>
<wui-dropdown-item-button active
>I'm a active button</wui-dropdown-item-button
>
<wui-dropdown-item-button disabled
>I'm a button, but disabled!</wui-dropdown-item-button
>
<wui-dropdown-item-button
>I don't look like a button, but I am!</wui-dropdown-item-button
>
</wui-dropdown>
</div>
<!-- wui-dropdown-item-button.vue -->
When the menu item doesn't trigger navigation, it is recommended to use the <wui-dropdown-item-button> sub-component.
<wui-dropdown-divider>
Separate groups of related menu items with <wui-dropdown-divider>.
<div>
<wui-dropdown id="dropdown-divider" text="Dropdown with divider" class="m-10">
<wui-dropdown-item-button>First item</wui-dropdown-item-button>
<wui-dropdown-item-button>Second item</wui-dropdown-item-button>
<wui-dropdown-divider></wui-dropdown-divider>
<wui-dropdown-item-button>Separated Item</wui-dropdown-item-button>
</wui-dropdown>
</div>
<!-- wui-dropdown-divider.vue -->
<wui-dropdown-text>
Place any freeform text within a dropdown menu using the <wui-dropdown-text> sub component or use text and use spacing utilities. Note that you'll likely need additional sizing styles to constrain/set the menu width.
<div>
<wui-dropdown id="dropdown-text" text="Dropdown with text" class="m-10">
<wui-dropdown-text style="width: 240px;">
Some example text that's free-flowing within the dropdown menu.
</wui-dropdown-text>
<wui-dropdown-text>And this is more example text.</wui-dropdown-text>
<wui-dropdown-divider></wui-dropdown-divider>
<wui-dropdown-item-button>First item</wui-dropdown-item-button>
<wui-dropdown-item-button>Second Item</wui-dropdown-item-button>
</wui-dropdown>
</div>
<!-- wui-dropdown-text.vue -->
<wui-dropdown-text> has the WuiVue custom class .dropdown-item-text applied to it which sets some basic styles which are suitable in most situations. By default its width will be the same as the widest <wui-dropdown-item> content. You may need to place additional styles or helper classes on the component.
By default <wui-dropdown-text> renders using tag <span>. You can change the rendered tag by setting the tag prop to any valid HTML5 tag on the <wui-dropdown-text> sub-component.
<wui-dropdown-form>
Dropdowns support basic forms. Put a <wui-dropdown-form> within a dropdown menu and place form controls within the <wui-dropdown-form>. The <wui-dropdown-form> is based on the <wui-form> component, and supports the same props and attributes as a regular form.
<template>
<div>
<wui-dropdown
id="dropdown-form"
text="Dropdown with form"
ref="dropdown"
class="m-10"
>
<wui-dropdown-form>
<wui-form-group
label="Email"
label-for="dropdown-form-email"
@submit.stop.prevent
>
<wui-form-input
id="dropdown-form-email"
size="sm"
placeholder="email@example.com"
></wui-form-input>
</wui-form-group>
<wui-form-group label="Password" label-for="dropdown-form-password">
<wui-form-input
id="dropdown-form-password"
type="password"
size="sm"
placeholder="Password"
></wui-form-input>
</wui-form-group>
<wui-form-checkbox class="m-b-15">Remember me</wui-form-checkbox>
<wui-button variant="primary" size="sm" @click="onClick"
>Sign In</wui-button
>
</wui-dropdown-form>
<wui-dropdown-divider></wui-dropdown-divider>
<wui-dropdown-item-button
>New around here? Sign up</wui-dropdown-item-button
>
<wui-dropdown-item-button>Forgot Password?</wui-dropdown-item-button>
</wui-dropdown>
</div>
</template>
<script>
export default {
methods: {
onClick() {
// Close the menu and (by passing true) return focus to the toggle button
this.$refs.dropdown.hide(true);
},
},
};
</script>
<!-- wui-dropdown-form.vue -->
<wui-dropdown-form> has the WuiVue custom class .wui-dropdown-form applied to it which sets some basic styles which are suitable in most situations. By default its width will be the same as the widest <wui-dropdown-item> content. You may need to place additional styles or helper classes on the component.
<wui-dropdown-group>
Group a set of dropdown sub components with an optional associated header. Place a <wui-dropdown-divider> between your <wui-dropdown-group> and other groups or non-grouped dropdown contents
<div>
<wui-dropdown id="dropdown-grouped" text="Dropdown with group" class="m-10">
<wui-dropdown-item-button> Non-grouped Item </wui-dropdown-item-button>
<wui-dropdown-divider></wui-dropdown-divider>
<wui-dropdown-group id="dropdown-group-1" header="Group 1">
<wui-dropdown-item-button>First Grouped item</wui-dropdown-item-button>
<wui-dropdown-item-button>Second Grouped Item</wui-dropdown-item-button>
</wui-dropdown-group>
<wui-dropdown-group id="dropdown-group-2" header="Group 2">
<wui-dropdown-item-button>First Grouped item</wui-dropdown-item-button>
<wui-dropdown-item-button>Second Grouped Item</wui-dropdown-item-button>
</wui-dropdown-group>
<wui-dropdown-divider></wui-dropdown-divider>
<wui-dropdown-item-button>
Another Non-grouped Item
</wui-dropdown-item-button>
</wui-dropdown>
</div>
<!-- wui-dropdown-group.vue -->
Using <wui-dropdown-group> instead of <wui-dropdown-header> is the recommended method for providing accessible grouped items with a header.
<wui-dropdown-header>
Add a header to label sections of actions in any dropdown menu.
<div>
<wui-dropdown id="dropdown-header" text="Dropdown with header" class="m-10">
<wui-dropdown-header id="dropdown-header-label">
Dropdown header
</wui-dropdown-header>
<wui-dropdown-item-button aria-describedby="dropdown-header-label">
First item
</wui-dropdown-item-button>
<wui-dropdown-item-button aria-describedby="dropdown-header-label">
Second Item
</wui-dropdown-item-button>
</wui-dropdown>
</div>
<!-- wui-dropdown-header.vue -->
See Section Dropdown headers and accessibility for details on making headers more accessible for users of assistive technologies.
Using the <wui-dropdown-group> sub-component simplifies creating accessible grouped dropdown items with an associated header.
Closing the menu via form interaction
Clicking buttons inside of a <wui-dropdown-form> will not automatically close the menu. If you need to close the menu using a button (or via the form submit event), call the hide() method on the <wui-dropdown> instance, as is shown in the above example.
The hide() method accepts a single boolean argument. If the argument is true, then focus will be returned to the dropdown toggle button after the menu has closed. Otherwise the document will gain focus once the menu is closed.
Optionally scoped default slot
The default slot is optionally scoped with the following scope available:
| Property or Method | Description |
|---|---|
hide() | Can be used to close the dropdown menu. Accepts an optional boolean argument, which if true returns focus to the toggle button |
Accessibility
Providing a unique id prop ensures ARIA compliance by automatically adding the appropriate aria-* attributes in the rendered markup.
The default ARIA role is set to menu, but you can change this default to another role (such as navigation) via the role prop, depending on your user case. The role prop value will be used to determine aria-haspopup attribute for the toggle button.
When a menu item doesn't trigger navigation, it is recommended to use the <wui-dropdown-item-button> sub-component (which is not announced as a link) instead of <wui-dropdown-item> (which is presented as a link to the user).
Headers and accessibility
When using <wui-dropdown-header> components in the dropdown menu, it is recommended to add an id attribute to each of the headers, and then set the aria-describedby attribute (set to the id value of the associated header) on each following dropdown items under that header. This will provide users of assistive technologies (i.e. sight-impaired users) additional context about the dropdown item:
<div>
<wui-dropdown
id="dropdown-aria"
text="Dropdown ARIA"
variant="primary"
class="m-10"
>
<wui-dropdown-header id="dropdown-header-1">Groups</wui-dropdown-header>
<wui-dropdown-item-button aria-describedby="dropdown-header-1"
>Add</wui-dropdown-item-button
>
<wui-dropdown-item-button aria-describedby="dropdown-header-1"
>Delete</wui-dropdown-item-button
>
<wui-dropdown-header id="dropdown-header-2">Users</wui-dropdown-header>
<wui-dropdown-item-button aria-describedby="dropdown-header-2"
>Add</wui-dropdown-item-button
>
<wui-dropdown-item-button aria-describedby="dropdown-header-2"
>Delete</wui-dropdown-item-button
>
<wui-dropdown-divider></wui-dropdown-divider>
<wui-dropdown-item-button>
Something <strong>not</strong> associated with Users
</wui-dropdown-item-button>
</wui-dropdown>
</div>
<!-- wui-dropdown-aria.vue -->
As a simplified alternative, use the <wui-dropdown-group> instead to easily associate header text to the contained dropdown sub-components.
Keyboard navigation
Dropdowns support keyboard navigation, emulating native <select> behaviour.
Note that Down and Up will not move focus into <wui-dropdown-form> sub components, but users can still use Tab or Shift+Tab to move into form controls within the menu.
Implementation notes
The dropdown menu is rendered with semantic <ul> and <li> elements for accessibility reasons. The .dropdown-menu is the <ul> element, while dropdown items (items, buttons, text, form, headers, and dividers) are wrapped in an <li> element. If creating custom items to place inside the dropdown menu, ensure they are wrapped with a plain <li>.
Component reference
<wui-dropdown>
Component aliases
<wui-dropdown> can also be used via the following aliases:
<wui-dd>
Note: component aliases are only available when importing all of WuiVue or using the component group plugin.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
block | Boolean | false | Renders a 100% width toggle button (expands to the width of its parent container) |
disabled | Boolean | false | When set to true, disables the component's functionality and places it in a disabled state |
centered | Boolean | false | Aligns the the menu at the center of the button |
dropleft | Boolean | false | When set, positions the menu to the left of the button |
dropright | Boolean | false | When set, positions the menu to the right of the button |
dropup | Boolean | false | When set, positions the menu on the top of the button |
fixed | Boolean | false | When set, position: fixed will be applied to the dropdown menu (instead of position: absolute) |
floating-ui-opts | Oject | {} | Additional configuration to pass to @floating-ui |
html | String | HTML string to place in the toggle button, or in the split button is split mode" | |
lazy | Boolean | false | When set, will only mount the menu content into the DOM when the menu is open |
menu-class | Array, Object or String | '' | CSS class (or classes) to add to the menu container |
menu-scroll-container | HTMLElement, Function, Object or String | menu | Custom HTML element, ref or HTML #id of the menu scroll container if you use a custom dropdown item layout |
menu-size | Boolean or Object | false | Options for the size middleware of @floating-ui |
menu-tag | String | '' | Specify the HTML tag to render the menu instead of the default tag |
no-caret | Boolean | false | Hide the caret indicator on the toggle button |
no-item-focus | Boolean | false | Dropdown will not focus the dropdown item when keyboard navigation is used, but will apply a CSS class instead to visualize the current selection |
no-flip | Boolean | false | Prevent the menu from auto flipping positions |
offset | Number, String or Object | 0 | Specify the number of pixels to shift the menu by. Negative values supported |
right | Boolean | false | Align the right edge of the menu with the right of the button |
role | String | 'menu' | Sets the ARIA attribute role to a specific value |
shift | Boolean or Object | false | shift() moves the floating element along the specified axes in order to keep it in view |
size | String | Set the size of the component's appearance. 'sm', 'md' (default), or 'lg' | |
split | Boolean | false | When set, renders a split button dropdown |
split-button-type | String | 'button' | Value to place in the 'type' attribute on the split button: 'button', 'submit', 'reset' |
split-class | Array, Object or String | CSS class (or classes) to add to the split button | |
splitHref | String | Denotes the target URL of the link for the split button | |
split-to | Object or String | <router-link> prop: Denotes the target route of the split button. When clicked, the value of the to prop will be passed to router.push() internally, so the value can be either a string or a Location descriptor object | |
split-variant | String | Applies one of the WUI theme color variants to the split button. Defaults to the 'variant' prop value | |
tag | String | 'div' | HTML tag to use for the dropdown wrapper element |
text | String | Text to place in the toggle button, or in the split button is split mode | |
toggle-attrs | Object | {} | Additional attributes to apply to the toggle button |
toggle-class | Array, Object or String | CSS class (or classes) to add to the toggle button | |
toggle-label | String | '' | ARIA label (sr-only) to set on the toggle when in split mode |
toggle-tag | String | 'button' | Specify the HTML tag to render instead of the default tag" |
translations | Object | see translations.js | The translation object to pass custom texts tag" |
variant | String | 'default' | Applies one of the WUI theme color variants to the component |
Slots
| Name | Scoped | Description |
|---|---|---|
button-content | No | Can be used to implement custom text with icons and more styling |
default | hide - Function - Can be used to close the dropdown menu. Accepts an optional boolean argument, which if true returns focus to the toggle button | Optionally scoped default slot for dropdown menu content |
Events
| Event | Arguments | Description |
|---|---|---|
click | event - Native click event object | Emitted when split button is clicked in split mode |
hidden | Emitted when dropdown is hidden | |
hide | wvEvent - WvEvent object. Call wvEvent.preventDefault() to cancel hide | Emitted just before dropdown is hidden. Cancelable |
show | wvEvent - WvEvent object. Call wvEvent.preventDefault() to cancel show | Emitted just before dropdown is shown. Cancelable |
shown | Emitted when dropdown is shown | |
toggle | Emitted when toggle button is clicked |
<wui-dropdown-item>
<wui-dropdown-item>Component aliases<wui-dropdown-item>Properties<wui-dropdown-item>Slots<wui-dropdown-item>Events
Component aliases
<wui-dropdown-item> can also be used via the following aliases:
<wui-dd-item>
Note: component aliases are only available when importing all of WuiVue or using the component group plugin.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
active | Boolean | false | When set to true, places the component in the active state with active styling |
active-class | String | <router-link> prop: Configure the active CSS class applied when the link is active. Typically you will want to set this to class name 'active' | |
append | Boolean | false | <router-link> prop: Setting append prop always appends the relative path to the current path |
disabled | Boolean | false | When set to true, disables the component's functionality and places it in a disabled state |
exact | Boolean | false | <router-link> prop: The default active class matching behavior is inclusive match. Setting this prop forces the mode to exactly match the route |
exact-active-class | String | <router-link> prop: Configure the active CSS class applied when the link is active with exact match. Typically you will want to set this to class name 'active' | |
exact-path | Boolean | false | <router-link> prop: Allows matching only using the path section of the url, effectively ignoring the query and the hash sections |
exact-path-active-class | String | <router-link> prop: Configure the active CSS class applied when the link is active with exact path match. Typically you will want to set this to class name 'active' | |
href | String | <wui-link> prop: Denotes the target URL of the link for standard a links | |
link-class | Array or Object or String | Class or classes to apply to the inner link element | |
no-close-on-click | Boolean | false | If set, the dropdown will not be closed when a dropdown item is clicked |
no-prefetch | Boolean | false | <nuxt-link> prop: To improve the responsiveness of your Nuxt.js applications, when the link will be displayed within the viewport, Nuxt.js will automatically prefetch the code splitted page. Setting no-prefetch will disabled this feature for the specific link |
prefetch | Boolean | null | <nuxt-link> prop: To improve the responsiveness of your Nuxt.js applications, when the link will be displayed within the viewport, Nuxt.js will automatically prefetch the code splitted page. Setting prefetch to true or false will overwrite the default value of router.prefetchLinks |
rel | String | null | <wui-link> prop: Sets the rel attribute on the rendered link |
replace | Boolean | false | <router-link> prop: Setting the replace prop will call router.replace() instead of router.push() when clicked, so the navigation will not leave a history record |
router-component-name | String | <wui-link> prop: WuiVue auto detects between <router-link> and <nuxt-link>. In cases where you want to use a 3rd party link component based on <router-link>, set this prop to the component name. e.g. set it to 'g-link' if you are using Gridsome (note only <router-link> specific props are passed to the component) | |
target | String | '_self' | <wui-link> prop: Sets the target attribute on the rendered link |
to | Object or String | <router-link> prop: Denotes the target route of the link. When clicked, the value of the to prop will be passed to router.push() internally, so the value can be either a string or a Location descriptor object | |
value | String, Number, Array, Object or Boolean | Unique value for this item. Will be emitted on dropdown item-mouseenter and item-mouseleave events | |
variant | String | Applies one of the WUI theme text color variants to the component |
Slots
| Name | Description |
|---|---|
default | Content to place in the dropdown item |
Events
| Event | Arguments | Description |
|---|---|---|
click | Native click event object | Emitted when item is clicked |
<wui-dropdown-item-button>
<wui-dropdown-item-button>Component aliases<wui-dropdown-item-button>Properties<wui-dropdown-item-button>Slots<wui-dropdown-item-button>Events
Component aliases
<wui-dropdown-item-button> can also be used via the following aliases:
<wui-dropdown-item-btn><wui-dd-item-button><wui-dd-item-btn>
Note: component aliases are only available when importing all of WuiVue or using the component group plugin.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
active | Boolean | false | When set to true, places the component in the active state with active styling |
active-class | String | <router-link> prop: Configure the active CSS class applied when the link is active. Typically you will want to set this to class name 'active' | |
button-class | Array, Object or String | Class or classes to apply to the inner button element | |
disabled | Boolean | false | When set to true, disables the component's functionality and places it in a disabled state |
variant | String | Applies one of the WUI theme text color variants to the component |
Slots
| Name | Description |
|---|---|
default | Content to place in the dropdown item-button |
Events
| Event | Arguments | Description |
|---|---|---|
click | Native click event object | Emitted when button item is clicked |
<wui-dropdown-divider>
Component aliases
<wui-dropdown-divider> can also be used via the following aliases:
<wui-dd-divider>
Note: component aliases are only available when importing all of WuiVue or using the component group plugin.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
tag | String | 'hr' | Specify the HTML tag to render instead of the default tag |
<wui-dropdown-form>
Component aliases
<wui-dropdown-form> can also be used via the following aliases:
<wui-dd-form>
Note: component aliases are only available when importing all of WuiVue or using the component group plugin.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
disabled | Boolean | false | When set to true, disables the component's functionality and places it in a disabled state |
form-class | Array, Object or String | CSS class (or classes) to add to the form | |
id | String | Used to set the id attribute on the rendered content, and used as the base to generate any additional element IDs as needed | |
inline | Boolean | false | When set, the form will be in inline mode which display labels, form controls, and buttons on a single horizontal row |
novalidate | Boolean | false | When set, disables browser native HTML5 validation on controls in the form |
Slots
| Name | Description |
|---|---|
default | Content to place in the dropdown form |
<wui-dropdown-text>
Component aliases
<wui-dropdown-text> can also be used via the following aliases:
<wui-dd-text>
Note: component aliases are only available when importing all of WuiVue or using the component group plugin.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
tag | String | 'span' | Specify the HTML tag to render instead of the default tag |
text-class | Array, Object or String | Class or classes to apply to the inner element | |
variant | String | Applies one of the WUI theme text color variants to the component |
Slots
| Name | Description |
|---|---|
default | Content to place in the dropdown text |
<wui-dropdown-group>
Component aliases
<wui-dropdown-group> can also be used via the following aliases:
<wui-dd-group>
Note: component aliases are only available when importing all of WuiVue or using the component group plugin.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
aria-describedby | String | The ID of the element that provides additional context for this component. Used as the value for the aria-describedby attribute | |
header | String | Text content to place in the header | |
header-classes | Array, Object or String | CSS class (or classes) to add to the header | |
header-tag | String | 'header' | Specify the HTML tag to render instead of the default tag for the header |
header-variant | String | Applies one of the WUI theme color variants to the header | |
id | String | Used to set the id attribute on the rendered content, and used as the base to generate any additional element IDs as needed |
Slots
| Name | Description |
|---|---|
default | Content (items) to place in the dropdown group |
header | Optional header content for the dropdown group |
<wui-dropdown-header>
Component aliases
<wui-dropdown-header> can also be used via the following aliases:
<wui-dd-header>
Note: component aliases are only available when importing all of WuiVue or using the component group plugin.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
id | String | Used to set the id attribute on the rendered content, and used as the base to generate any additional element IDs as needed | |
tag | String | 'header' | Specify the HTML tag to render instead of the default tag |
variant | String | Applies one of the WUI theme color variants to the component |
Slots
| Name | Description |
|---|---|
default | Content to place in the dropdown header |
Importing individual components
You can import individual components into your project via the following named exports:
| Component | Named Export |
|---|---|
<wui-dropdown> | WuiDropdown |
<wui-dropdown-item> | WuiDropdownItem |
<wui-dropdown-item-button> | WuiDropdownItemButton |
<wui-dropdown-divider> | WuiDropdownDivider |
<wui-dropdown-form> | WuiDropdownForm |
<wui-dropdown-text> | WuiDropdownText |
<wui-dropdown-group> | WuiDropdownGroup |
<wui-dropdown-header> | WuiDropdownHeader |
Example
import { WuiDropdown } from "@wui/wui-vue/lib/dropdown";
Vue.component("wui-dropdown", WuiDropdown);
Importing as a Vue.js plugin
This plugin includes all of the above listed individual components. Plugins also include any component aliases.
| Named Export | Import Path |
|---|---|
DropdownPlugin | @wui/wui-vue/lib/dropdown |
Example
import { DropdownPlugin } from "@wui/wui-vue/lib/dropdown";
Vue.use(DropdownPlugin);
