Docs

Main site

Installation Browser support Extend config MCP server
Validation Page speed testing Responsive design
Accordion Aspect Ratio Avatar Badge Banner Bento Grid Blockquote Breadcrumbs Button Callout Card Drawer Dropdown Link Modal Navbar Navblock Pagination Popover Progress Separator Tabs Timeline Toast Tooltip
Checkbox Datepicker File upload Form field Input Label OTP Radio Range Select Textarea Toggle
Header Footer
Accordion Auth Checkbox & Radio Content Drawers Features Modals Statistics & Metrics Teams Dropdowns
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Components Dropdown

Dropdown

A Dropdown reveals a menu of actions, navigation links, or grouped commands anchored to a trigger element. "aegov-dropdown" pairs a trigger (the default slot) with a "dropdown-content" slot, rendering the menu into a portal at the document body so it can escape ancestor clipping and stacking contexts.

Overlay Navigation Interactive
Status
Active
Introduced
4.0.x
View source code

Anatomy

aegov-dropdown pairs a trigger with a menu panel that is rendered into a portal at document.body on open, positioned relative to the trigger, and animated in.

Image showing anatomy of a dropdown

Item Name Description
1 Trigger The default-slotted element the user interacts with — a button, link, or avatar
2 Panel The portaled menu surface — position, alignment, gap, and offset apply here
3 Menu item Each focusable child inside dropdown-content — a link, button, or <hr> separator

Trigger type

trigger controls how the dropdown opens. click (default) toggles the dropdown on click and closes it on outside click or Escape. hover opens on pointer-enter after delay-start, and closes on pointer-leave with a 100ms grace period so the cursor can cross the gap between trigger and panel. Both accept Enter/Space on a focused trigger, so keyboard users are never limited to hover-only interaction.

<aegov-dropdown trigger="click">
  <aegov-button variant="primary">Service actions</aegov-button>
  <div slot="dropdown-content">
    <a href="#renew">Renew application</a>
    <a href="#duplicate">Request duplicate</a>
    <a href="#cancel">Cancel application</a>
  </div>
</aegov-dropdown>
<aegov-dropdown trigger="hover">
  <aegov-button variant="secondary" appearance="soft">Services</aegov-button>
  <div slot="dropdown-content">
    <a href="/visa">Visa services</a>
    <a href="/passport">Passport services</a>
    <a href="/emirates-id">Emirates ID services</a>
  </div>
</aegov-dropdown>

Position

position sets the preferred placement of the panel relative to the trigger. If there is not enough room on the preferred edge, the dropdown automatically flips to the opposite edge.

<aegov-dropdown position="top">
  <aegov-button>Top</aegov-button>
  <div slot="dropdown-content">
    <a href="#a">First option</a>
    <a href="#b">Second option</a>
  </div>
</aegov-dropdown>
<aegov-dropdown position="right">
  <aegov-button>Right</aegov-button>
  <div slot="dropdown-content">
    <a href="#a">First option</a>
    <a href="#b">Second option</a>
  </div>
</aegov-dropdown>
<aegov-dropdown position="bottom">
  <aegov-button>Bottom</aegov-button>
  <div slot="dropdown-content">
    <a href="#a">First option</a>
    <a href="#b">Second option</a>
  </div>
</aegov-dropdown>
<aegov-dropdown position="left">
  <aegov-button>Left</aegov-button>
  <div slot="dropdown-content">
    <a href="#a">First option</a>
    <a href="#b">Second option</a>
  </div>
</aegov-dropdown>

Alignment and offset

align positions the panel along the cross axis of the placement — for position="bottom"/"top" this is horizontal, for "left"/"right" it is vertical. gap controls the pixel distance between trigger and panel along the placement axis; offset shifts the panel along the cross axis without affecting alignment.

Align start Align center Align end, 16px gap
<aegov-dropdown align="start">
  <aegov-button>Align start</aegov-button>
  <div slot="dropdown-content">
    <a href="#a">First option</a>
    <a href="#b">Second option</a>
  </div>
</aegov-dropdown>
<aegov-dropdown align="center">
  <aegov-button>Align center</aegov-button>
  <div slot="dropdown-content">
    <a href="#a">First option</a>
    <a href="#b">Second option</a>
  </div>
</aegov-dropdown>
<aegov-dropdown align="end" gap="16">
  <aegov-button>Align end, 16px gap</aegov-button>
  <div slot="dropdown-content">
    <a href="#a">First option</a>
    <a href="#b">Second option</a>
  </div>
</aegov-dropdown>

Disabled state

Set is-disabled="true" to make the trigger inert. The dropdown will not open via click, hover, or keyboard until the property is removed.

Unavailable actions
<aegov-dropdown is-disabled="true">
  <aegov-button is-disabled="true">Unavailable actions</aegov-button>
  <div slot="dropdown-content">
    <a href="#a">This menu is disabled</a>
  </div>
</aegov-dropdown>

Nested dropdowns

A nested dropdown is a child aegov-dropdown placed inside the dropdown-content slot of a parent. Any depth is supported: opening a nested dropdown does not close its parent, and the parent stays open while the cursor is over the child or its panel. Each level renders into its own portal.

<aegov-dropdown>
  <aegov-button variant="primary">Apply for service</aegov-button>
  <div slot="dropdown-content">
    <a href="#new">New application</a>
    <aegov-dropdown trigger="hover" position="right">
      <a href="#">Visa services ›</a>
      <div slot="dropdown-content">
        <a href="/visa/visit">Visit visa</a>
        <a href="/visa/work">Work visa</a>
        <a href="/visa/golden">Golden visa</a>
      </div>
    </aegov-dropdown>
    <hr />
    <a href="#status">Check application status</a>
  </div>
</aegov-dropdown>

Programmatic control

Call the public toggle() method on the host element to open or close the dropdown from your own code — useful for driving the same menu from a second trigger elsewhere on the page. Pass true as the first argument when the call originated from a keyboard handler, so the first menu item receives focus per the ARIA menu pattern.

<aegov-dropdown field-id="ministry-switcher" align="end">
  <aegov-button variant="secondary">Switch ministry</aegov-button>
  <div slot="dropdown-content">
    <a href="#moi">Ministry of Interior</a>
    <a href="#mofa">Ministry of Foreign Affairs</a>
    <a href="#moh">Ministry of Health</a>
  </div>
</aegov-dropdown>

<aegov-button variant="secondary" id="open-from-outside">Open from outside</aegov-button>

<script>
  var dd = document.querySelector('[field-id="ministry-switcher"]');
  document.getElementById('open-from-outside').addEventListener('click', function () {
    dd.toggle(false);
  });
</script>

Composing with real content

A dropdown anchored to an avatar in a header, and an action menu on a table row — two of the most common real-world patterns. Use align="end" so the panel hugs the trailing edge of the trigger.

FH Fatima Al Hammadi

Passport renewal — APP-2026-00482

Submitted 12 April 2026

<div class="flex justify-end">
  <aegov-dropdown align="end" position="bottom">
    <aegov-button appearance="soft">
      <aegov-avatar size="sm" appearance="rounded">FH</aegov-avatar>
      Fatima Al Hammadi
    </aegov-button>
    <div slot="dropdown-content">
      <a href="/profile">My profile</a>
      <a href="/applications">My applications</a>
      <hr />
      <a href="/signout">Sign out</a>
    </div>
  </aegov-dropdown>
</div>
<div class="flex items-center justify-between border border-aeblack-200 rounded p-4">
  <div>
    <p class="text-base font-medium">Passport renewal — APP-2026-00482</p>
    <p class="text-sm">Submitted 12 April 2026</p>
  </div>
  <aegov-dropdown align="end" position="bottom">
    <aegov-button appearance="soft" size="sm" aria-label="Row actions">
      <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
        <circle cx="3" cy="8" r="1.5" fill="currentColor"/>
        <circle cx="8" cy="8" r="1.5" fill="currentColor"/>
        <circle cx="13" cy="8" r="1.5" fill="currentColor"/>
      </svg>
    </aegov-button>
    <div slot="dropdown-content">
      <a href="#view">View details</a>
      <a href="#edit">Edit application</a>
      <hr />
      <a href="#cancel">Cancel application</a>
    </div>
  </aegov-dropdown>
</div>

React only: when it opens, aegov-dropdown moves its dropdown-content to the end of document.body so it can escape clipping and stack above the page. React listens for events on your app's root element, so a plain onClick, onChange or onInput on anything inside the dropdown-content slot never fires. Use the wrapper's own events instead — onAegovButtonClick on AegovButton — or bind native elements such as <button> with addEventListener through a ref (see Using with React). Links with an href need no handler and work as usual. The trigger in the default slot is not moved, so its handlers work.

RTL support

Dropdowns are direction-agnostic: when the host or an ancestor is dir="rtl", slot content inherits the document's direction, including text alignment inside menu items and the panel's own reading-direction text alignment.

<div dir="rtl">
  <aegov-dropdown align="end" position="bottom">
    <aegov-button variant="primary">إجراءات الحساب</aegov-button>
    <div slot="dropdown-content">
      <a href="/profile">الملف الشخصي</a>
      <a href="/applications">طلباتي</a>
      <hr />
      <a href="/signout">تسجيل الخروج</a>
    </div>
  </aegov-dropdown>
</div>

Usage

Here is the recommended usage of a dropdown on any website or application. These are recommended usage guides, however the developer must use the best practices of web and application development to accurately use this component.

Place a single, clearly-labelled focusable element in the trigger slot
A button, link, or avatar with visible text or an aria-label — never bare, unlabelled content the trigger's purpose can't be inferred from.

Use hr to group related menu items
A thin divider between "safe" actions and a destructive one (sign out, delete, cancel) gives users a visual pause before an irreversible choice.

Reach for tab-behavior="disclosure" for navigation sub-menus
A dropdown used as a nav bar's sub-menu should let Tab move through its links naturally rather than trapping focus like an action menu — this is exactly what aegov-navbar-item sets automatically.

Do not nest more than one or two levels of dropdown
Each level of nested dropdown adds a hover/keyboard path a user must track. Beyond a second level, restructure the content into a dedicated page or a aegov-navblock instead.

Do not use a dropdown for a single destructive action
A one-item "Delete" menu adds an extra click for no benefit — use a plain button (with a confirmation step if needed) instead of hiding it behind a dropdown.

API reference

The following are the properties and references of a dropdown

aegov-dropdown properties

AttributeDescriptionTypeDefault

field-id

DOM id for the menu element. Auto-generated if omitted. The trigger receives a derived ${field-id}-trigger id for ARIA linkage.

string

auto-generated

trigger

How the dropdown opens.

click | hover

click

tab-behavior

ARIA keyboard pattern. menu-button traps Tab/Shift+Tab inside the menu, cycling with wraparound. disclosure lets Tab move through the menu's links and closes the menu once focus moves past the last/first item — set automatically by aegov-navbar-item when the dropdown is used as a nav sub-menu.

menu-button | disclosure

menu-button

position

Preferred placement relative to the trigger. Auto-flips to the opposite edge if there is not enough room.

top | right | bottom | left

bottom

align

Cross-axis alignment of the panel against the trigger.

start | center | end

start

gap

Pixel distance between the trigger and the panel along the placement axis.

number

8

offset

Additional pixel offset along the cross axis.

number

0

is-disabled

When true, the trigger is inert and the dropdown will not open via click, hover, or keyboard.

boolean

false

delay-start

Milliseconds to wait before opening. Mainly relevant for trigger="hover".

number

200

delay-end

Milliseconds to wait before closing on hover-out. A 100ms grace period always applies for hover so the cursor can cross the gap between trigger and panel.

number

0

Slots

SlotDescription

(default)

Trigger element. Should be a single focusable element such as aegov-button, a native button, a link, or an avatar.

dropdown-content

Menu contents — anchors, buttons, <hr> separators, or any HTML. Moved into the portal on open, moved back on close.

Events

EventDetailDescription

aegovDropdownOpen

void

Fired when the dropdown opens.

aegovDropdownClose

void

Fired when the dropdown closes, for any reason.

Methods

MethodReturnsDescription

toggle(viaKeyboard?: boolean, viaArrow?: boolean)

Promise<void>

Toggle the dropdown open/closed regardless of trigger. Pass viaKeyboard: true from keyboard handlers so the first menu item receives focus per the ARIA menu pattern; viaArrow: true when the call originated from an ArrowDown/ArrowUp handler.

closeDropdown()

Promise<void>

Close the dropdown programmatically.

Pass-through attributes

AttributeNotesForwards to

aria-*

Forwarded to the trigger wrapper so it can describe the trigger semantically.

trigger wrapper

data-*

Forwarded to the trigger wrapper.

trigger wrapper

id

Not forwarded. Use field-id — it sets the menu's real id and derives the trigger's.

n/a

class, style

Applied to the host element — stays host-only, never forwarded inward.

host

Notes

The following notes are applicable of this component.

Built-in accessibility

  • The first focusable element inside the trigger slot (e.g. aegov-button) automatically receives aria-haspopup="menu", aria-expanded, and aria-controls (pointing at the menu's id when open). These attributes are set imperatively so they live on the element assistive technology actually reads, not the wrapper <div>.
  • The menu element has role="menu" and aria-labelledby linking back to the trigger wrapper's id (tab-behavior="menu-button" only — disclosure mode uses no menu semantics, since it represents plain navigation links, not commands).
  • Focusable children inside the menu without an explicit role automatically receive role="menuitem" (menu-button mode only).
  • Escape closes the dropdown and returns focus to the trigger, using preventScroll so the page does not jump if the trigger has scrolled out of view.
  • Keyboard-triggered opens (Enter/Space, or Arrow Down/Arrow Up on the closed trigger) move focus into the menu; pointer opens leave focus on the trigger, matching the WAI-ARIA menu-button pattern.
  • Only one dropdown is open at a time — opening another automatically closes the previous one. Nested dropdowns are exempt: opening a child does not close its parent.
  • The dropdown auto-closes if its trigger scrolls out of the viewport, and re-positions on every scroll and resize.

Developer responsibilities

  • Place a single focusable element in the default slot — a button, link, or avatar with a role/tabindex. The component does not add tab-stop behaviour to arbitrary non-focusable slotted content.
  • Provide an accessible name on the trigger — visible text, aria-label, or aria-labelledby. This matters especially for icon-only triggers such as a row-actions kebab button.
  • Ensure every menu item is keyboard-activatable — links, buttons, or elements with a real tabindex.
  • For destructive items (delete, cancel, sign out) make the consequence clear in the label text; do not rely on colour alone, and consider a divider (<hr>) to separate them from routine actions.
  • Reach for tab-behavior="disclosure" when the dropdown represents a navigation sub-menu (links to other pages) rather than a set of commands — aegov-navbar-item sets this automatically.

Keyboard support

Key Function
Enter, Space Toggles the dropdown when the trigger has focus.
Arrow Down Opens the dropdown (focusing the first item) when the trigger has focus and the menu is closed; moves focus to the next item when the menu is open.
Arrow Up Opens the dropdown (focusing the last item) when the trigger has focus and the menu is closed; moves focus to the previous item when the menu is open.
Home Moves focus to the first menu item.
End Moves focus to the last menu item.
A-Z, 0-9 Type-ahead: moves focus to the next menu item whose label starts with the typed character(s) (500ms reset between keystrokes).
Tab menu-button mode: moves focus to the next menu item, wrapping to the first after the last. disclosure mode: moves through the menu's links, closing the menu once focus moves past the last item.
Shift + Tab menu-button mode: moves focus to the previous menu item, wrapping to the last after the first. disclosure mode: moves backward through the menu's links, closing the menu once focus moves past the first item.
Escape Closes the dropdown and returns focus to the trigger.