Skip to content
PatternFly.org Contribute on Github
PatternFly Elements
Versions v4 v3 v2 v1

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/elements

Then 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

Action Link Disabled Action Link
Separated Action
Separated Link

Installation

npm install @patternfly/elements

Usage

Basic

The following example shows a few different states of dropdown items. As shown in this example, dropdown items may:

This example also uses an hr to split the menu into 2 sections with a horizontal line.

Action Link Disabled Action Link
Separated Action Separated Link
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.

My Custom Dropdown Action Link Disabled Action Link
Separated Action Separated Link
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.

Action Link Disabled Action Link
Separated Action Separated Link
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.

Action Link
Group 2 action Group 2 link
Group 3 action Group 3 link
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.

Action This is a description Link This is a very long description that describes the menu item Disabled action Disabled action description Disabled link Disabled link description
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>

Use the icon slot to add an icon.

User Lock
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.

Action Link
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.

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 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 description slot

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

© 2018-2024 Red Hat, Inc. Deploys by Netlify