Dropdown

<wa-dropdown>

Since 2.0

stable

Dropdowns display a list of options that can be triggered by a button or other element. They support keyboard navigation, submenus, and various customization options.

Dropdowns consist of a trigger and a panel. By default, activating the trigger will expose the panel and interacting outside of the panel will close it.

Dropdowns are designed to work well with dropdown items to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications. The API gives you complete control over showing, hiding, and positioning the panel.

                
  Dropdown

    Cut
  
    Copy
  
    Paste
  
    Show images
    Show All Images
    Show Thumbnails
  
  Emoji Shortcuts
  Word Wrap
  
    Delete

<wa-dropdown>
  <wa-button slot="trigger" with-caret>Dropdown</wa-button>

  <wa-dropdown-item>
    <wa-icon slot="icon" name="scissors"></wa-icon>
    Cut
  </wa-dropdown-item>
  <wa-dropdown-item>
    <wa-icon slot="icon" name="copy"></wa-icon>
    Copy
  </wa-dropdown-item>
  <wa-dropdown-item>
    <wa-icon slot="icon" name="paste"></wa-icon>
    Paste
  </wa-dropdown-item>
  <wa-divider></wa-divider>
  <wa-dropdown-item>
    Show images
    <wa-dropdown-item slot="submenu" value="show-all-images">Show All Images</wa-dropdown-item>
    <wa-dropdown-item slot="submenu" value="show-thumbnails">Show Thumbnails</wa-dropdown-item>
  </wa-dropdown-item>
  <wa-divider></wa-divider>
  <wa-dropdown-item type="checkbox" checked>Emoji Shortcuts</wa-dropdown-item>
  <wa-dropdown-item type="checkbox" checked>Word Wrap</wa-dropdown-item>
  <wa-divider></wa-divider>
  <wa-dropdown-item variant="danger">
    <wa-icon slot="icon" name="trash"></wa-icon>
    Delete
  </wa-dropdown-item>
</wa-dropdown>

Examples Jump to heading

Getting the Selected Item Jump to heading

When an item is selected, the wa-select event will be emitted by the dropdown. You can inspect event.detail.item to get a reference to the selected item. If you've provided a value for each dropdown item, it will be available in event.detail.item.value.

  
    View
    Enter full screen
    Actual size
    Zoom in
    Zoom out

<div class="dropdown-selection">
  <wa-dropdown>
    <wa-button slot="trigger" with-caret>View</wa-button>
    <wa-dropdown-item value="full-screen">Enter full screen</wa-dropdown-item>
    <wa-dropdown-item value="actual">Actual size</wa-dropdown-item>
    <wa-dropdown-item value="zoom-in">Zoom in</wa-dropdown-item>
    <wa-dropdown-item value="zoom-out">Zoom out</wa-dropdown-item>
  </wa-dropdown>
</div>

<script>
  const container = document.querySelector('.dropdown-selection');
  const dropdown = container.querySelector('wa-dropdown');

  dropdown.addEventListener('wa-select', event => {
    console.log(event.detail.item.value);
  });
</script>

To keep the dropdown open after selection, call event.preventDefault() in the wa-select event's callback.

Showing Icons Jump to heading

Use the icon slot to add icons to dropdown items. This works best with icon elements.

                
  Edit

    Cut
  
    Copy
  
    Paste
  
    Delete

<wa-dropdown>
  <wa-button slot="trigger" with-caret>Edit</wa-button>

  <wa-dropdown-item value="cut">
    <wa-icon slot="icon" name="scissors"></wa-icon>
    Cut
  </wa-dropdown-item>

  <wa-dropdown-item value="copy">
    <wa-icon slot="icon" name="copy"></wa-icon>
    Copy
  </wa-dropdown-item>

  <wa-dropdown-item value="paste">
    <wa-icon slot="icon" name="paste"></wa-icon>
    Paste
  </wa-dropdown-item>

  <wa-dropdown-item value="delete" variant="danger">
    <wa-icon slot="icon" name="trash"></wa-icon>
    Delete
  </wa-dropdown-item>
</wa-dropdown>

Showing Labels & Dividers Jump to heading

Use any heading, e.g. <h1>–<h6> to add labels and the <wa-divider> element for separators.

                
  Device

  Type
  Phone
  Tablet
  Desktop

  More options…

<wa-dropdown>
  <wa-button slot="trigger" with-caret>Device</wa-button>

  <h3>Type</h3>
  <wa-dropdown-item value="phone">Phone</wa-dropdown-item>
  <wa-dropdown-item value="tablet">Tablet</wa-dropdown-item>
  <wa-dropdown-item value="desktop">Desktop</wa-dropdown-item>

  <wa-divider></wa-divider>

  <wa-dropdown-item value="more">More options…</wa-dropdown-item>
</wa-dropdown>

Showing Details Jump to heading

Use the details slot to display details, such as keyboard shortcuts, inside dropdown items.

                
  Message

    Reply
    ⌘R
  
    Forward
    ⌘F
  
    Move
    ⌘M
  
    Archive
    ⌘A
  
    Delete
    Del

<wa-dropdown>
  <wa-button slot="trigger" with-caret>Message</wa-button>

  <wa-dropdown-item value="reply">
    Reply
    <span slot="details">⌘R</span>
  </wa-dropdown-item>

  <wa-dropdown-item value="forward">
    Forward
    <span slot="details">⌘F</span>
  </wa-dropdown-item>

  <wa-dropdown-item value="move">
    Move
    <span slot="details">⌘M</span>
  </wa-dropdown-item>

  <wa-divider></wa-divider>

  <wa-dropdown-item value="archive">
    Archive
    <span slot="details">⌘A</span>
  </wa-dropdown-item>

  <wa-dropdown-item value="delete" variant="danger">
    Delete
    <span slot="details">Del</span>
  </wa-dropdown-item>
</wa-dropdown>

Checkable Items Jump to heading

You can turn a dropdown item into a checkable option by setting type="checkbox". Add the checked attribute to make it checked initially. When clicked, the item's checked state will toggle and the dropdown will close. You can cancel the wa-select event if you want to keep it open instead.

  
    View

    Show canvas
    Show grid
    Show source

    Preferences…

<div class="dropdown-checkboxes">
  <wa-dropdown>
    <wa-button slot="trigger" with-caret>View</wa-button>

    <wa-dropdown-item type="checkbox" value="canvas" checked>Show canvas</wa-dropdown-item>
    <wa-dropdown-item type="checkbox" value="grid" checked>Show grid</wa-dropdown-item>
    <wa-dropdown-item type="checkbox" value="source">Show source</wa-dropdown-item>

    <wa-divider></wa-divider>

    <wa-dropdown-item value="preferences">Preferences…</wa-dropdown-item>
  </wa-dropdown>
</div>

<script>
  const container = document.querySelector('.dropdown-checkboxes');
  const dropdown = container.querySelector('wa-dropdown');

  dropdown.addEventListener('wa-select', event => {
    if (event.detail.item.type === 'checkbox') {
      // Checkbox
      console.log(event.detail.item.value, event.detail.item.checked ? 'checked' : 'unchecked');
    } else {
      // Not a checkbox
      console.log(event.detail.item.value);
    }
  });
</script>

When a checkable option exists anywhere in the dropdown, all items will receive additional padding so they align properly.

Destructive Items Jump to heading

Add variant="danger" to any dropdown item to highlight that it's a dangerous action.

                
  Project

    Share
  
    Preferences
  
  Danger zone

    Archive
  
    Delete

<wa-dropdown>
  <wa-button slot="trigger" with-caret>Project</wa-button>

  <wa-dropdown-item value="share">
    <wa-icon slot="icon" name="share"></wa-icon>
    Share
  </wa-dropdown-item>

  <wa-dropdown-item value="preferences">
    <wa-icon slot="icon" name="gear"></wa-icon>
    Preferences
  </wa-dropdown-item>

  <wa-divider></wa-divider>

  <h3>Danger zone</h3>

  <wa-dropdown-item value="archive">
    <wa-icon slot="icon" name="archive"></wa-icon>
    Archive
  </wa-dropdown-item>

  <wa-dropdown-item value="delete" variant="danger">
    <wa-icon slot="icon" name="trash"></wa-icon>
    Delete
  </wa-dropdown-item>
</wa-dropdown>

Placement Jump to heading

The preferred placement of the dropdown can be set with the placement attribute. Note that the actual position may vary to ensure the panel remains in the viewport.

                
    File formats
    
  PDF Document
  Word Document
  Excel Spreadsheet
  PowerPoint Presentation
  Plain Text
  JSON File

<wa-dropdown placement="right-start">
  <wa-button slot="trigger">
    File formats
    <wa-icon slot="end" name="chevron-right"></wa-icon>
  </wa-button>

  <wa-dropdown-item value="pdf">PDF Document</wa-dropdown-item>
  <wa-dropdown-item value="docx">Word Document</wa-dropdown-item>
  <wa-dropdown-item value="xlsx">Excel Spreadsheet</wa-dropdown-item>
  <wa-dropdown-item value="pptx">PowerPoint Presentation</wa-dropdown-item>
  <wa-dropdown-item value="txt">Plain Text</wa-dropdown-item>
  <wa-dropdown-item value="json">JSON File</wa-dropdown-item>
</wa-dropdown>

Distance Jump to heading

The distance from the panel to the trigger can be customized using the distance attribute. This value is specified in pixels.

                
  Edit

  Cut
  Copy
  Paste

  Find
  Replace

<wa-dropdown distance="30">
  <wa-button slot="trigger" with-caret>Edit</wa-button>

  <wa-dropdown-item>Cut</wa-dropdown-item>
  <wa-dropdown-item>Copy</wa-dropdown-item>
  <wa-dropdown-item>Paste</wa-dropdown-item>

  <wa-divider></wa-divider>

  <wa-dropdown-item>Find</wa-dropdown-item>
  <wa-dropdown-item>Replace</wa-dropdown-item>
</wa-dropdown>

Offset Jump to heading

The offset of the panel along the trigger can be customized using the skidding attribute. This value is specified in pixels.

                
  Edit

  Cut
  Copy
  Paste

  Find
  Replace

<wa-dropdown skidding="30">
  <wa-button slot="trigger" with-caret>Edit</wa-button>

  <wa-dropdown-item>Cut</wa-dropdown-item>
  <wa-dropdown-item>Copy</wa-dropdown-item>
  <wa-dropdown-item>Paste</wa-dropdown-item>

  <wa-divider></wa-divider>

  <wa-dropdown-item>Find</wa-dropdown-item>
  <wa-dropdown-item>Replace</wa-dropdown-item>
</wa-dropdown>

Submenus Jump to heading

To create submenus, nest dropdown items inside of a dropdown item and assign slot="submenu" to each one. You can also add dividers as needed.

  
    Export

      Documents
      PDF
      Word Document
    
      Spreadsheets
      
        Excel Formats
        Excel (.xlsx)
        Excel 97-2003 (.xls)
        CSV (.csv)
      
        Other Formats
        OpenDocument (.ods)
        Tab-separated (.tsv)
        JSON (.json)
      
      Apple Numbers
    
      Options
      Compress files
      Include metadata
      Password protect

<div class="dropdown-submenus">
  <wa-dropdown>
    <wa-button slot="trigger" with-caret>Export</wa-button>

    <wa-dropdown-item>
      Documents
      <wa-dropdown-item slot="submenu" value="pdf">PDF</wa-dropdown-item>
      <wa-dropdown-item slot="submenu" value="docx">Word Document</wa-dropdown-item>
    </wa-dropdown-item>

    <wa-dropdown-item>
      Spreadsheets
      <wa-dropdown-item slot="submenu">
        Excel Formats
        <wa-dropdown-item slot="submenu" value="xlsx">Excel (.xlsx)</wa-dropdown-item>
        <wa-dropdown-item slot="submenu" value="xls">Excel 97-2003 (.xls)</wa-dropdown-item>
        <wa-dropdown-item slot="submenu" value="csv">CSV (.csv)</wa-dropdown-item>
      </wa-dropdown-item>

      <wa-dropdown-item slot="submenu">
        Other Formats
        <wa-dropdown-item slot="submenu" value="ods">OpenDocument (.ods)</wa-dropdown-item>
        <wa-dropdown-item slot="submenu" value="tsv">Tab-separated (.tsv)</wa-dropdown-item>
        <wa-dropdown-item slot="submenu" value="json">JSON (.json)</wa-dropdown-item>
      </wa-dropdown-item>

      <wa-dropdown-item slot="submenu" value="numbers">Apple Numbers</wa-dropdown-item>
    </wa-dropdown-item>

    <wa-divider></wa-divider>

    <wa-dropdown-item>
      Options
      <wa-dropdown-item slot="submenu" type="checkbox" value="compress">Compress files</wa-dropdown-item>
      <wa-dropdown-item slot="submenu" type="checkbox" checked value="metadata">Include metadata</wa-dropdown-item>
      <wa-dropdown-item slot="submenu" type="checkbox" value="password">Password protect</wa-dropdown-item>
    </wa-dropdown-item>
  </wa-dropdown>
</div>

<script>
  const container = document.querySelector('.dropdown-submenus');
  const dropdown = container.querySelector('wa-dropdown');

  dropdown.addEventListener('wa-select', event => {
    console.log(event.detail.item.value);
  });
</script>

Dropdown items that have a submenu will not dispatch the wa-select event. However, items inside the submenu will, unless they also have a submenu.

As a UX best practice, avoid using more than one level of submenu when possible.

Disabling Items Jump to heading

Add the disabled attribute to any dropdown item to disable it.

                
  Payment method

  Cash
  Personal check
  Credit card
  Gift card

<wa-dropdown>
  <wa-button slot="trigger" with-caret>Payment method</wa-button>

  <wa-dropdown-item value="cash">Cash</wa-dropdown-item>
  <wa-dropdown-item value="check" disabled>Personal check</wa-dropdown-item>
  <wa-dropdown-item value="credit">Credit card</wa-dropdown-item>
  <wa-dropdown-item value="gift-card">Gift card</wa-dropdown-item>
</wa-dropdown>

Slots Jump to heading

Learn more about using slots.

Name	Description
(default)	The dropdown's items, typically `<wa-dropdown-item>` elements.
`trigger`	The element that triggers the dropdown, such as a `<wa-button>` or `<button>`.

Attributes & Properties Jump to heading

Learn more about attributes and properties.

Name	Description	Reflects
`open` `open`	Opens or closes the dropdown. Type `boolean` Default `false`
`size` `size`	The dropdown's size. Type `'small' \| 'medium' \| 'large'` Default `'medium'`
`placement` `placement`	The placement of the dropdown menu in reference to the trigger. The menu will shift to a more optimal location if the preferred placement doesn't have enough room. Type `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'right' \| 'right-start' \| 'right-end' \| 'left' \| 'left-start' \| 'left-end'` Default `'bottom-start'`
`distance` `distance`	The distance of the dropdown menu from its trigger. Type `number` Default `0`
`skidding` `skidding`	The offset of the dropdown menu along its trigger. Type `number` Default `0`

Events Jump to heading

Learn more about events.

Name	Description
`wa-show`	Emitted when the dropdown is about to show.
`wa-after-show`	Emitted after the dropdown has been shown.
`wa-hide`	Emitted when the dropdown is about to hide.
`wa-after-hide`	Emitted after the dropdown has been hidden.
`wa-select`	Emitted when an item in the dropdown is selected.

CSS custom properties Jump to heading

Learn more about CSS custom properties.

Name	Description
`--show-duration`	The duration of the show animation.
`--hide-duration`	The duration of the hide animation.

CSS parts Jump to heading

Learn more about CSS parts.

Name	Description	CSS selector
`base`	The component's host element.	`::part(base)`
`menu`	The dropdown menu container.	`::part(menu)`

Dependencies Jump to heading

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

Importing Jump to heading

Autoloading components via projects is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.

CDN

npm

React

Let your project code do the work! Sign up for free to use a project with your very own CDN — it's the fastest and easiest way to use Web Awesome.

To manually import this component from NPM, use the following code.

import '@awesome.me/webawesome/dist/components/dropdown/dropdown.js';

To manually import this component from React, use the following code.

import WaDropdown from '@awesome.me/webawesome/dist/react/dropdown';

Need a hand?

Report a bug

Ask for help

Getting Started

Resources

Components

Style Utilities

Layout

Patterns

Theming

Design Tokens

Terms & Policies

Web Awesome

Web Awesome Elsewhere

Dropdown

Examples Jump to heading

Getting the Selected Item Jump to heading

Showing Icons Jump to heading

Showing Labels & Dividers Jump to heading

Type

Showing Details Jump to heading

Checkable Items Jump to heading

Destructive Items Jump to heading

Danger zone

Placement Jump to heading

Distance Jump to heading

Offset Jump to heading

Submenus Jump to heading

Disabling Items Jump to heading

Slots Jump to heading

Attributes & Properties Jump to heading

Events Jump to heading

CSS custom properties Jump to heading

CSS parts Jump to heading

Dependencies Jump to heading

Importing Jump to heading

Get a lifetime discount on Web Awesome Pro!