Dropdown

<wa-dropdown>

Since 2.0

stable

Dropdowns expose additional content that "drops down" in a panel.

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 menus to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. color picker). The API gives you complete control over showing, hiding, and positioning the panel.

Dropdown

Dropdown Item 1

Dropdown Item 2

Dropdown Item 3

Checkbox

Disabled

Prefix

Suffix Icon

<wa-dropdown>
  <wa-button slot="trigger" caret>Dropdown</wa-button>
  <wa-menu>
    <wa-menu-item>Dropdown Item 1</wa-menu-item>
    <wa-menu-item>Dropdown Item 2</wa-menu-item>
    <wa-menu-item>Dropdown Item 3</wa-menu-item>
    <wa-divider></wa-divider>
    <wa-menu-item type="checkbox" checked>Checkbox</wa-menu-item>
    <wa-menu-item disabled>Disabled</wa-menu-item>
    <wa-divider></wa-divider>
    <wa-menu-item>
      Prefix
      <wa-icon slot="prefix" name="gift" variant="solid"></wa-icon>
    </wa-menu-item>
    <wa-menu-item>
      Suffix Icon
      <wa-icon slot="suffix" name="heart" variant="solid"></wa-icon>
    </wa-menu-item>
  </wa-menu>
</wa-dropdown>

Examples Jump to heading

Getting the Selected Item Jump to heading

When dropdowns are used with menus, you can listen for the wa-select event to determine which menu item was selected. The menu item element will be exposed in event.detail.item. You can set value props to make it easier to identify commands.

<div class="dropdown-selection">
  <wa-dropdown>
    <wa-button slot="trigger" caret>Edit</wa-button>
    <wa-menu>
      <wa-menu-item value="cut">Cut</wa-menu-item>
      <wa-menu-item value="copy">Copy</wa-menu-item>
      <wa-menu-item value="paste">Paste</wa-menu-item>
    </wa-menu>
  </wa-dropdown>
</div>

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

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

Alternatively, you can listen for the click event on individual menu items. Note that, using this approach, disabled menu items will still emit a click event.

<div class="dropdown-selection-alt">
  <wa-dropdown>
    <wa-button slot="trigger" caret>Edit</wa-button>
    <wa-menu>
      <wa-menu-item value="cut">Cut</wa-menu-item>
      <wa-menu-item value="copy">Copy</wa-menu-item>
      <wa-menu-item value="paste">Paste</wa-menu-item>
    </wa-menu>
  </wa-dropdown>
</div>

<script>
  const container = document.querySelector('.dropdown-selection-alt');
  const cut = container.querySelector('wa-menu-item[value="cut"]');
  const copy = container.querySelector('wa-menu-item[value="copy"]');
  const paste = container.querySelector('wa-menu-item[value="paste"]');

  cut.addEventListener('click', () => console.log('cut'));
  copy.addEventListener('click', () => console.log('copy'));
  paste.addEventListener('click', () => console.log('paste'));
</script>

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.

Edit

Cut

Copy

Paste

Find

Replace

<wa-dropdown placement="top-start">
  <wa-button slot="trigger" caret>Edit</wa-button>
  <wa-menu>
    <wa-menu-item>Cut</wa-menu-item>
    <wa-menu-item>Copy</wa-menu-item>
    <wa-menu-item>Paste</wa-menu-item>
    <wa-divider></wa-divider>
    <wa-menu-item>Find</wa-menu-item>
    <wa-menu-item>Replace</wa-menu-item>
  </wa-menu>
</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" caret>Edit</wa-button>
  <wa-menu>
    <wa-menu-item>Cut</wa-menu-item>
    <wa-menu-item>Copy</wa-menu-item>
    <wa-menu-item>Paste</wa-menu-item>
    <wa-divider></wa-divider>
    <wa-menu-item>Find</wa-menu-item>
    <wa-menu-item>Replace</wa-menu-item>
  </wa-menu>
</wa-dropdown>

Skidding 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" caret>Edit</wa-button>
  <wa-menu>
    <wa-menu-item>Cut</wa-menu-item>
    <wa-menu-item>Copy</wa-menu-item>
    <wa-menu-item>Paste</wa-menu-item>
    <wa-divider></wa-divider>
    <wa-menu-item>Find</wa-menu-item>
    <wa-menu-item>Replace</wa-menu-item>
  </wa-menu>
</wa-dropdown>

Submenus Jump to heading

To create a submenu, nest an <wa-menu slot="submenu"> element in a menu item.

Edit

Undo

Redo

Cut

Copy

Paste

Find

Find…

Find Next

Find Previous

Transformations

Make uppercase

Make lowercase

Capitalize

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

  <wa-menu style="max-width: 200px;">
    <wa-menu-item value="undo">Undo</wa-menu-item>
    <wa-menu-item value="redo">Redo</wa-menu-item>
    <wa-divider></wa-divider>
    <wa-menu-item value="cut">Cut</wa-menu-item>
    <wa-menu-item value="copy">Copy</wa-menu-item>
    <wa-menu-item value="paste">Paste</wa-menu-item>
    <wa-divider></wa-divider>
    <wa-menu-item>
      Find
      <wa-menu slot="submenu">
        <wa-menu-item value="find">Find…</wa-menu-item>
        <wa-menu-item value="find-previous">Find Next</wa-menu-item>
        <wa-menu-item value="find-next">Find Previous</wa-menu-item>
      </wa-menu>
    </wa-menu-item>
    <wa-menu-item>
      Transformations
      <wa-menu slot="submenu">
        <wa-menu-item value="uppercase">Make uppercase</wa-menu-item>
        <wa-menu-item value="lowercase">Make lowercase</wa-menu-item>
        <wa-menu-item value="capitalize">Capitalize</wa-menu-item>
      </wa-menu>
    </wa-menu-item>
  </wa-menu>
</wa-dropdown>

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

Hoisting Jump to heading

Dropdown panels will be clipped if they're inside a container that has overflow: auto|hidden. The hoist attribute forces the panel to use a fixed positioning strategy, allowing it to break out of the container. In this case, the panel will be positioned relative to its containing block, which is usually the viewport unless an ancestor uses a transform, perspective, or filter. Refer to this page for more details.

<div class="dropdown-hoist">
  <wa-dropdown>
    <wa-button slot="trigger" caret>No Hoist</wa-button>
    <wa-menu>
      <wa-menu-item>Item 1</wa-menu-item>
      <wa-menu-item>Item 2</wa-menu-item>
      <wa-menu-item>Item 3</wa-menu-item>
    </wa-menu>
  </wa-dropdown>

  <wa-dropdown hoist>
    <wa-button slot="trigger" caret>Hoist</wa-button>
    <wa-menu>
      <wa-menu-item>Item 1</wa-menu-item>
      <wa-menu-item>Item 2</wa-menu-item>
      <wa-menu-item>Item 3</wa-menu-item>
    </wa-menu>
  </wa-dropdown>
</div>

<style>
  .dropdown-hoist {
    position: relative;
    border: solid 2px var(--wa-color-surface-border);
    padding: var(--wa-space-m);
    overflow: hidden;
  }
</style>

Slots Jump to heading

Name	Description
(default)	The dropdown's main content.
`trigger`	The dropdown's trigger, usually a `<wa-button>` element.

Properties Jump to heading

Name	Description	Reflects
`open` `open`	Indicates whether or not the dropdown is open. You can toggle this attribute to show and hide the dropdown, or you can use the `show()` and `hide()` methods and this attribute will reflect the dropdown's open state. Type `boolean` Default `false`
`placement` `placement`	The preferred placement of the dropdown panel. Note that the actual placement may vary as needed to keep the panel inside of the viewport. Type `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'right' \| 'right-start' \| 'right-end' \| 'left' \| 'left-start' \| 'left-end'` Default `'bottom-start'`
`disabled` `disabled`	Disables the dropdown so the panel will not open. Type `boolean` Default `false`
`stayOpenOnSelect` `stay-open-on-select`	By default, the dropdown is closed when an item is selected. This attribute will keep it open instead. Useful for dropdowns that allow for multiple interactions. Type `boolean` Default `false`
`containingElement`	The dropdown will close when the user interacts outside of this element (e.g. clicking). Useful for composing other components that use a dropdown internally. Type `HTMLElement \| undefined`
`distance` `distance`	The distance in pixels from which to offset the panel away from its trigger. Type `number` Default `0`
`skidding` `skidding`	The distance in pixels from which to offset the panel along its trigger. Type `number` Default `0`
`hoist` `hoist`	Enable this option to prevent the panel from being clipped when the component is placed inside a container with `overflow: auto\|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios. Type `boolean` Default `false`
`sync` `sync`	Syncs the popup width or height to that of the trigger element. Type `'width' \| 'height' \| 'both' \| undefined` Default `undefined`

Methods Jump to heading

Name	Description	Arguments
`show()`	Shows the dropdown panel.
`hide()`	Hides the dropdown panel
`reposition()`	Instructs the dropdown menu to reposition. Useful when the position or size of the trigger changes when the menu is activated.

Events Jump to heading

Name	Description
`wa-show`	Emitted when the dropdown opens.
`wa-after-show`	Emitted after the dropdown opens and all animations are complete.
`wa-hide`	Emitted when the dropdown closes.
`wa-after-hide`	Emitted after the dropdown closes and all animations are complete.

CSS custom properties Jump to heading

Name	Description
`--box-shadow`	The shadow effects around the dropdown's edges.

CSS parts Jump to heading

Name	Description
`base`	The component's base wrapper, a `<wa-popup>` element.
`base__popup`	The popup's exported `popup` part. Use this to target the tooltip's popup container.
`trigger`	The container that wraps the trigger.
`panel`	The panel that gets shown when the dropdown is open.

Dependencies Jump to heading

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

<wa-popup>

Importing Jump to heading

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

CDN

npm

React

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

import 'https://early.webawesome.com/webawesome@3.0.0-alpha.4/dist/components/dropdown/dropdown.js';

Coming soon!

Dropdown

Examples Jump to heading #

Getting the Selected Item Jump to heading #

Placement Jump to heading #

Distance Jump to heading #

Skidding Jump to heading #

Submenus Jump to heading #

Hoisting Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods 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 #

Examples Jump to heading

Getting the Selected Item Jump to heading

Placement Jump to heading

Distance Jump to heading

Skidding Jump to heading

Submenus Jump to heading

Hoisting Jump to heading

Slots Jump to heading

Properties Jump to heading

Methods 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