Dropdown
A dropdown presents a menu of actions or links in a constrained space that will trigger a process or navigate to a new location.
Installation
We recommend loading elements via a CDN such as JSPM and using an import map to manage your dependencies.
For more information on import maps and how to use them, see the import map reference on MDN Web Docs.
If you are using node and NPM, you can install this component using npm:
npm install @patternfly/elementsThen import this component into your project by using a bare module specifier:
import '@patternfly/elements/pf-dropdown/pf-dropdown.js';Please Note You should either load elements via a CDN or install them locally through NPM. Do not do both.
Overview
Installation
npm install @patternfly/elementsUsage
Basic
The following example shows a few different states of dropdown items. As shown in this example, dropdown items may:
- Use the
disabledproperty to disable an item. - Use the
hrefproperty to make the item a link.
This example also uses an hr to split the menu into 2 sections with a horizontal line.
View HTML Source
<pf-dropdown>
<pf-dropdown-item>Action</pf-dropdown-item>
<pf-dropdown-item href="#">Link</pf-dropdown-item>
<pf-dropdown-item disabled>Disabled Action</pf-dropdown-item>
<pf-dropdown-item disabled href="#">Link</pf-dropdown-item>
<hr>
<pf-dropdown-item>Separated Action</pf-dropdown-item>
<pf-dropdown-item href="#">Separated Link</pf-dropdown-item>
</pf-dropdown>
Custom toggle
A custom toggle can be added using the toggle slot.
View HTML Source
<pf-dropdown>
<pf-button slot="toggle" variant="control">
My Custom Dropdown
<svg viewBox="0 0 320 512" fill="currentColor" aria-hidden="true" width="1em" height="1em"><path d="M31.3 192h257.3c17.8 0 26.7 21.5 14.1 34.1L174.1 354.8c-7.8 7.8-20.5 7.8-28.3 0L17.2 226.1C4.6 213.5 13.5 192 31.3 192z"></path></svg>
</pf-button>
<pf-dropdown-item>Action</pf-dropdown-item>
<pf-dropdown-item href="#">Link</pf-dropdown-item>
<pf-dropdown-item disabled>Disabled Action</pf-dropdown-item>
<pf-dropdown-item disabled href="#">Link</pf-dropdown-item>
<hr>
<pf-dropdown-item>Separated Action</pf-dropdown-item>
<pf-dropdown-item href="#">Separated Link</pf-dropdown-item>
</pf-dropdown>
With kebab toggle
When there isn't enough space for a labeled button, a slotted toggle button with a kebab icon (three dots) can be used to toggle the dropdown menu open or closed. Make sure to add an aria-label to the toggle so that assistive technology users know what the button is.
View HTML Source
<pf-dropdown>
<pf-button slot="toggle" aria-label="Toggle" plain>
<svg viewBox="0 0 192 512" fill="currentColor" aria-hidden="true" role="img" width="1em" height="1em"><path d="M96 184c39.8 0 72 32.2 72 72s-32.2 72-72 72-72-32.2-72-72 32.2-72 72-72zM24 80c0 39.8 32.2 72 72 72s72-32.2 72-72S135.8 8 96 8 24 40.2 24 80zm0 352c0 39.8 32.2 72 72 72s72-32.2 72-72-32.2-72-72-72-72 32.2-72 72z"></path></svg>
</pf-button>
<pf-dropdown-item>Action</pf-dropdown-item>
<pf-dropdown-item href="#">Link</pf-dropdown-item>
<pf-dropdown-item disabled>Disabled Action</pf-dropdown-item>
<pf-dropdown-item disabled href="#">Link</pf-dropdown-item>
<hr>
<pf-dropdown-item>Separated Action</pf-dropdown-item>
<pf-dropdown-item href="#">Separated Link</pf-dropdown-item>
</pf-dropdown>
With groups of items
To group sets of related dropdown items together, use a pf-dropdown-group. When more than 1 pf-dropdown-group is created in a menu, use the label and labelHeadingLevel properties to assign a name and heading level to each group.
View HTML Source
<pf-dropdown>
<pf-dropdown-group>
<pf-dropdown-item>Action</pf-dropdown-item>
<pf-dropdown-item href="#">Link</pf-dropdown-item>
</pf-dropdown-group>
<hr>
<pf-dropdown-group label="Group 2">
<pf-dropdown-item>Group 2 action</pf-dropdown-item>
<pf-dropdown-item href="#">Group 2 link</pf-dropdown-item>
</pf-dropdown-group>
<hr>
<pf-dropdown-group label="Group 3">
<pf-dropdown-item>Group 3 action</pf-dropdown-item>
<pf-dropdown-item href="#">Group 3 link</pf-dropdown-item>
</pf-dropdown-group>
</pf-dropdown>
With item descriptions
To provide users with more context about a pf-dropdown-item, pass a short message to description slot. As shown in the example below, an item's description will appear below its label.
View HTML Source
<pf-dropdown>
<pf-dropdown-item>
Action
<span slot="description">This is a description</span>
</pf-dropdown-item>
<pf-dropdown-item href="#">
Link
<span slot="description">This is a very long description that describes the menu item</span>
</pf-dropdown-item>
<pf-dropdown-item disabled>
Disabled action
<span slot="description">Disabled action description</span>
</pf-dropdown-item>
<pf-dropdown-item disabled href="#">
Disabled link
<span slot="description">Disabled link description</span>
</pf-dropdown-item>
</pf-dropdown>
Dropdown with icon
Use the icon slot to add an icon.
View HTML Source
<pf-dropdown>
<pf-dropdown-item>
<pf-icon icon="user" aria-label="user" size="md" slot="icon"></pf-icon>
User
</pf-dropdown-item>
<pf-dropdown-item>
<pf-icon icon="lock" aria-label="user" size="md" slot="icon"></pf-icon>
Lock
</pf-dropdown-item>
</pf-dropdown>
Disabled dropdown
Use the disabled attribute to disable an entire dropdown.
View HTML Source
<pf-dropdown disabled>
<pf-dropdown-item>Action</pf-dropdown-item>
<pf-dropdown-item href="#">Link</pf-dropdown-item>
</pf-dropdown>
Accessibility
The dropdown uses the Menu Button Pattern recommendations from the WAI ARIA Authoring Best Practices Guide (APG).
Note: WAI-ARIA recommends elements of a larger composite widget remain focusable.
Menu button
When focus is on the menu button, the following keyboard interactions apply:
| Key | Function |
|---|---|
| Enter | Opens the menu. |
| Space | Opens the menu. |
| Down arrow | Opens the menu and moves focus to the first menu item. |
| Tab | Moves focus out of dropdown element onto the next focusable item and closes menu. |
| Shift+Tab | Moves focus out of dropdown element onto the previous focusable item and closes menu. |
Menu items
Menu items use the APG's Roving tabindex recommendation. When focus is on the menu items, the following keyboard interactions apply:
| Key | Function |
|---|---|
| Enter | Activates the item and closes the menu. |
| Space | Activates the item and closes the menu. |
| Tab | Moves focus out of dropdown element onto the next focusable item and closes menu. |
| Shift+Tab | Moves focus to the menu button and closes menu. |
| Up Arrow | Moves focus to the previous item, optionally wrapping from the first to the last. |
| Down Arrow | Moves focus to the next item, optionally wrapping from the last to the first. |
| Left Arrow | Moves focus to the previous item, optionally wrapping from the first to the last. |
| Right Arrow | Moves focus to the next item, optionally wrapping from the last to the first. |
| Home | Moves focus to the first item in the current menu. |
| End | Moves focus to the last item in the current menu. |
| Escape | Close the menu that contains focus and return focus to the menu button. |
Slots
- Default Slot
-
Must contain one or more
<pf-dropdown-item>or<pf-dropdown-group> -
toggle -
Custom toggle button
-
menu -
when using a custom toggle, you must slot a
<pf-dropdown-menu>in alongside it
Slots on pf-dropdown-item
-
icon -
Optional slot for an icon
-
description -
Optional slot for item description
- Default Slot
-
Content for the dropdown item
Slots on pf-dropdown-group
- Default Slot
-
Content for the group of dropdown items
Attributes
disabled-
When disabled, the dropdown can still be toggled open and closed via keyboard, but menu items cannot be activated.
- DOM Property
disabled- Type
-
boolean - Default
-
false
expanded-
Whether the dropdown is expanded
- DOM Property
expanded- Type
-
boolean - Default
-
false
Slots on pf-dropdown-item
value-
The value associated with the dropdown item. This value can be used to identify the selected item
- DOM Property
value- Type
-
string | undefined - Default
-
unknown
href-
href for link dropdown items
- DOM Property
href- Type
-
string | undefined - Default
-
unknown
active-
Flag indicating whether the item is active
- DOM Property
active- Type
-
boolean - Default
-
false
disabled-
Indicates whether the dropdown item is disabled. A disabled item cannot be selected.
- DOM Property
disabled- Type
-
boolean - Default
-
false
description-
Item description; overridden by
descriptionslot- DOM Property
description- Type
-
string | undefined - Default
-
unknown
Slots on pf-dropdown-group
label-
The label for the group of dropdown items.
- DOM Property
label- Type
-
string | undefined - Default
-
unknown
Methods
show()-
Opens the dropdown
hide()-
Closes the dropdown
toggle()
Slots on pf-dropdown-item
None
Slots on pf-dropdown-group
None
Events
select-
when a user select dropdown value
Event Type:PfDropdownSelectEvent open-
when the dropdown toggles open
Event Type:unknown close-
when the dropdown toggles closed
Event Type:unknown
Slots on pf-dropdown-item
None
Slots on pf-dropdown-group
None
CSS Custom Properties
| CSS Property | Description | Default |
|---|---|---|
--pf-c-dropdown__menu--PaddingTop |
Dropdown top padding |
0.5rem
|
--pf-c-tooltip__content--PaddingRight |
Dropdown right padding |
0.5rem
|
--pf-c-dropdown__menu--ZIndex |
Dropdown z-index |
200
|
--pf-c-dropdown__menu--BoxShadow |
Dropdown box shadow |
0 0.25rem 0.5rem 0rem rgba(3, 3, 3, 0.12), 0 0 0.25rem 0 rgba(3, 3, 3, 0.06)
|
--pf-c-dropdown__menu--Top |
Dropdown top |
100% + 0.25rem
|
CSS Properties on pf-dropdown-item
| CSS Property | Description | Default |
|---|---|---|
--pf-c-dropdown__menu-item--FontSize |
Dropdown item font size |
1rem
|
--pf-c-dropdown__menu-item--FontWeight |
Dropdown item font weight |
400
|
--pf-c-dropdown__menu-item--LineHeight |
Dropdown item line height |
1.5
|
--pf-c-dropdown__menu-item--Color |
Dropdown item color |
#151515
|
--pf-c-dropdown__menu-item--BackgroundColor |
Dropdown item background color |
transparent
|
--pf-c-dropdown__menu-item--PaddingTop |
Dropdown item padding top |
0.5rem
|
--pf-c-dropdown__menu-item--PaddingRight |
Dropdown item padding right |
1rem
|
--pf-c-dropdown__menu-item--PaddingBottom |
Dropdown item padding bottom |
0.5rem
|
--pf-c-dropdown__menu-item--PaddingLeft |
Dropdown item padding left |
1rem
|
CSS Properties on pf-dropdown-group
None
CSS Shadow Parts
menu-
The dropdown menu wrapper
Parts on pf-dropdown-item
None
Parts on pf-dropdown-group
None
