Dropdown
<ahi-dropdown> | AhiDropdown
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.
<ahi-dropdown>
<ahi-button slot="trigger" disclosure>Dropdown</ahi-button>
<ahi-menu>
<ahi-menu-item>Dropdown Item 1</ahi-menu-item>
<ahi-menu-item>Dropdown Item 2</ahi-menu-item>
<ahi-menu-item>Dropdown Item 3</ahi-menu-item>
<ahi-divider></ahi-divider>
<ahi-menu-item type="checkbox" checked>Checked</ahi-menu-item>
<ahi-menu-item disabled>Disabled</ahi-menu-item>
<ahi-divider></ahi-divider>
<ahi-menu-item>
Prefix
<ahi-icon slot="prefix" name="home"></ahi-icon>
</ahi-menu-item>
<ahi-menu-item>
Suffix Icon
<ahi-icon slot="suffix" name="settings"></ahi-icon>
</ahi-menu-item>
</ahi-menu>
</ahi-dropdown>
Examples
Getting the selected item
When dropdowns are used with menus, you can listen for the
ahi-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 items.
<ahi-dropdown class="dropdown-selection">
<ahi-button slot="trigger" disclosure>Edit</ahi-button>
<ahi-menu>
<ahi-menu-item value="cut">Cut</ahi-menu-item>
<ahi-menu-item value="copy">Copy</ahi-menu-item>
<ahi-menu-item value="paste">Paste</ahi-menu-item>
</ahi-menu>
</ahi-dropdown>
<script>
const dropdown = document.querySelector('.dropdown-selection');
dropdown.addEventListener('ahi-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.
<ahi-dropdown class="dropdown-alternative-selection">
<ahi-button slot="trigger" disclosure>Edit</ahi-button>
<ahi-menu>
<ahi-menu-item value="cut">Cut</ahi-menu-item>
<ahi-menu-item value="copy">Copy</ahi-menu-item>
<ahi-menu-item value="paste">Paste</ahi-menu-item>
</ahi-menu>
</ahi-dropdown>
<script>
const container = document.querySelector('.dropdown-alternative-selection');
const cut = container.querySelector('ahi-menu-item[value="cut"]');
const copy = container.querySelector('ahi-menu-item[value="copy"]');
const paste = container.querySelector('ahi-menu-item[value="paste"]');
cut.addEventListener('click', () => console.log('cut'));
copy.addEventListener('click', () => console.log('copy'));
paste.addEventListener('click', () => console.log('paste'));
</script>
Placement
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.
<ahi-dropdown placement="top-start">
<ahi-button slot="trigger" disclosure="up">Edit</ahi-button>
<ahi-menu>
<ahi-menu-item>Cut</ahi-menu-item>
<ahi-menu-item>Copy</ahi-menu-item>
<ahi-menu-item>Paste</ahi-menu-item>
<ahi-divider></ahi-divider>
<ahi-menu-item>Find</ahi-menu-item>
<ahi-menu-item>Replace</ahi-menu-item>
</ahi-menu>
</ahi-dropdown>
Distance
The distance from the panel to the trigger can be customized using the distance attribute. This
value is specified in pixels.
<ahi-dropdown distance="30">
<ahi-button slot="trigger" disclosure>Edit</ahi-button>
<ahi-menu>
<ahi-menu-item>Cut</ahi-menu-item>
<ahi-menu-item>Copy</ahi-menu-item>
<ahi-menu-item>Paste</ahi-menu-item>
<ahi-divider></ahi-divider>
<ahi-menu-item>Find</ahi-menu-item>
<ahi-menu-item>Replace</ahi-menu-item>
</ahi-menu>
</ahi-dropdown>
Skidding
The offset of the panel along the trigger can be customized using the skidding attribute. This
value is specified in pixels.
<ahi-dropdown skidding="30">
<ahi-button slot="trigger" disclosure>Edit</ahi-button>
<ahi-menu>
<ahi-menu-item>Cut</ahi-menu-item>
<ahi-menu-item>Copy</ahi-menu-item>
<ahi-menu-item>Paste</ahi-menu-item>
<ahi-divider></ahi-divider>
<ahi-menu-item>Find</ahi-menu-item>
<ahi-menu-item>Replace</ahi-menu-item>
</ahi-menu>
</ahi-dropdown>
Submenus
To create a submenu, nest an <ahi-menu slot="submenu"> element in a
menu item.
<ahi-dropdown>
<ahi-button slot="trigger" disclosure>Edit</ahi-button>
<ahi-menu style="max-width: 200px;">
<ahi-menu-item value="undo">Undo</ahi-menu-item>
<ahi-menu-item value="redo">Redo</ahi-menu-item>
<ahi-divider></ahi-divider>
<ahi-menu-item value="cut">Cut</ahi-menu-item>
<ahi-menu-item value="copy">Copy</ahi-menu-item>
<ahi-menu-item value="paste">Paste</ahi-menu-item>
<ahi-divider></ahi-divider>
<ahi-menu-item>
Find
<ahi-menu slot="submenu">
<ahi-menu-item value="find">Find…</ahi-menu-item>
<ahi-menu-item value="find-previous">Find Next</ahi-menu-item>
<ahi-menu-item value="find-next">Find Previous</ahi-menu-item>
</ahi-menu>
</ahi-menu-item>
<ahi-menu-item>
Transformations
<ahi-menu slot="submenu">
<ahi-menu-item value="uppercase">Make uppercase</ahi-menu-item>
<ahi-menu-item value="lowercase">Make lowercase</ahi-menu-item>
<ahi-menu-item value="capitalize">Capitalize</ahi-menu-item>
</ahi-menu>
</ahi-menu-item>
</ahi-menu>
</ahi-dropdown>
As a UX best practice, avoid using more than one level of submenu when possible.
Hoisting
Dropdown panels are rendered in the browser’s
native top layer, so they automatically break out of containers with overflow: auto|hidden|scroll and are not
clipped — even when nested inside a scrolling or transformed ancestor. Both dropdowns below render their
panel above the clipping container without any extra configuration.
The hoist attribute is deprecated and will be removed in a future major. It
has no effect in browsers that support the
Popover API
(all current browsers); it is only consulted as a fallback in older browsers, where it switches the panel
to a fixed positioning strategy. Remove it from your markup — no replacement is needed, since
panels escape clipping containers on their own.
<div class="dropdown-hoisting">
<ahi-dropdown>
<ahi-button slot="trigger" disclosure>Open</ahi-button>
<ahi-menu>
<ahi-menu-item>Item 1</ahi-menu-item>
<ahi-menu-item>Item 2</ahi-menu-item>
<ahi-menu-item>Item 3</ahi-menu-item>
</ahi-menu>
</ahi-dropdown>
</div>
<style>
.dropdown-hoisting {
position: relative;
border: solid 2px var(--ahi-border-neutral-subdued);
padding: var(--ahi-space-5);
overflow: hidden;
}
</style>
Importing
To import this component using a script tag:
<script type="module" src="/path/to/azalea-kit-ui/dist/components/dropdown/dropdown.js"></script>To import this component using a bundler:
import '@azaleahealth/azalea-kit-ui/dist/components/dropdown/dropdown.js';Slots
| Name | Description |
|---|---|
| (default) | The dropdown’s main content. |
trigger
|
The dropdown’s trigger, usually a <ahi-button> element. |
Learn more about using slots.
Properties
| Name | Description | Type | Default | |
|---|---|---|---|---|
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. |
HTMLElement | undefined
|
- | |
disabled
|
Disables the dropdown so the panel will not open. |
boolean
|
false
|
|
distance
|
The distance in pixels from which to offset the panel away from its trigger. |
number
|
0
|
|
hoist
|
Deprecated. Enabled a fixed positioning strategy to keep the panel from being
clipped by a container with overflow: auto|scroll. The panel now renders in the
browser’s native top layer, which escapes clipping containers on its own, so this has no effect
except as a fallback on browsers without Popover API support. Remove it from your markup; no
replacement is needed.
|
boolean
|
false
|
|
sync
|
Syncs the popup width or height to that of the trigger element. |
'width' | 'height' | 'both' | undefined
|
undefined
|
|
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.
|
boolean
|
false
|
|
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. |
'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'right' |
'right-start' | 'right-end' | 'left' | 'left-start' | 'left-end'
|
'bottom-start'
|
|
skidding
|
The distance in pixels from which to offset the panel along its trigger. |
number
|
0
|
|
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. |
boolean
|
false
|
|
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about properties and attributes.
Events
| Name | Description | Event Detail |
|---|---|---|
ahi-show |
Emitted when the dropdown opens. Call event.preventDefault() to keep the dropdown from
opening.
|
- |
ahi-after-show |
Emitted after the dropdown opens and all animations are complete. | - |
ahi-hide |
Emitted when the dropdown closes. Call event.preventDefault() to keep the dropdown from
closing.
|
- |
ahi-after-hide |
Emitted after the dropdown closes and all animations are complete. | - |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
reposition() |
Instructs the dropdown menu to reposition. Useful when the position or size of the trigger changes when the menu is activated. | - |
Learn more about methods.
CSS Parts
| Name | Description |
|---|---|
base |
Deprecated. Use the dropdown part instead. |
dropdown |
The component’s outer wrapper. |
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. |
Learn more about customizing CSS parts.
Animations
| Name | Description |
|---|---|
dropdown.show |
The animation to use when showing the dropdown. |
dropdown.hide |
The animation to use when hiding the dropdown. |
Learn more about customizing animations.
Dependencies
This component automatically imports the following dependencies.
<ahi-popup>