Dropdown

A click-triggered menu that opens anchored to the trigger element.

Basic usage

Trigger on click

Actions

Example

Trigger

The trigger attribute controls how the menu opens: click (default) / hover / focus, multi-selectable with spaces (e.g. "click hover"). With hover, hover-delay / hover-hide-delay debounce open/close (default 150 / 100ms — without a delay hover flickers). The hover area is the trigger plus the floating panel (moving across the gap does not close it).

Hover trigger

Hover to open

Example

Focus trigger

Focus to open (Tab or click)

Example

Multiple triggers (click + hover)

Click or hover

Example

Custom hover delays

hover-delay=400hover-hide-delay=400

Example

Placement

Four directions

UpDownLeftRight

Example

12-way placement

placement supports 12 directions: each of the four bases (top / bottom / left / right) pairs with a cross-axis -start / -end align (bottom-start — the panel's left edge aligns with the trigger's left edge — is the most common form). When the panel flips along the main axis due to lack of space, the align suffix is preserved (bottom-start → top-start), and the aligned position is still clamped to the viewport.

12-way placement

bottom-startbottom-endright-starttop-end

Example

Nested submenus

items entries support a children array for cascading submenus (any depth); hover/click expands, selecting a leaf collapses and closes. The floating menu reuses oas-menu, so nested submenus automatically flip left/up near viewport edges to stay fully visible.

Nested submenus

More actions

Example

Disabled items

Disabled items

Actions

Example

Disabled dropdown

disabled disables the whole dropdown: click / hover / focus triggers are ignored, the split arrow button is disabled, the host is desaturated (opacity .6) and syncs aria-disabled.

Disabled dropdown

Disabled (click)Disabled (split)

Example

Arrow

The menu panel shows an arrow pointing at the trigger element . The arrow attribute toggles it (shown by default; arrow="false" hides it). arrow-point-at-center pins the arrow to the panel center (by default the arrow follows the trigger's projection, so it still points at the trigger even after viewport-avoidance shifting). auto-adjust-overflow controls whether the placement auto-flips when there is not enough viewport space (enabled by default).

With arrow

With arrow

Example

Arrow visibility

Default (arrow)arrow="false"

Example

Arrow at center & no overflow adjust

arrow-point-at-centerauto-adjust-overflow="false"

Example

Selection event

Selection event

Select an actionNothing selected

Example

Keep open after select

hide-on-click controls whether selecting a menu item closes the menu (default true — close on select; "false" keeps it open, useful for multi-select / check scenarios).

Keep open after select

Keep openNothing selected

Example

Controlled display

The open attribute is controlled: an external button can set/remove open to show/hide the menu (clicking outside / pressing Esc / selecting an item still closes it).

Controlled display (open attribute)

OpenCloseopen: falseTrigger element

Example

Open-change event

The component fires oas-open-change (detail: { open }) whenever it opens or closes itself (click / hover / focus / Esc / outside click / select) — the host can sync state in controlled mode (same semantics as tooltip / popover; externally writing open also triggers it).

oas-open-change event

Click or hoveropen: false

Example

Offset & scroll

offset adjusts the gap between the panel and the trigger (default 8px). When the page scrolls, the panel repositions to follow the trigger (fixing the fixed-positioning detachment); close-on-scroll closes it on scroll instead.

Offset

Default (8px)offset=16

Example

Close on scroll

Open then scroll the page

Example

Controlled selection

The value attribute is controlled: an external value sets the selected item (the dropdown shows no check mark, so a tag echoes the current value in real time); selecting a menu item also updates value and fires oas-select.

Controlled selection (value attribute)

Select "Edit"Select "Copy"Clearvalue: -Select an action

Example

Split button

The split attribute turns the dropdown into a split button : a main button plus a separate arrow button. Click the arrow to open the menu; clicking the main button fires oas-action (bind your primary action, e.g. save); selecting a menu item still fires oas-select.

Split button

Save & submit

Example

Main button action event

More actionsNot clicked yet

Example

Loading menu items

A menu item with loading: true enters a loading state: it shows a spinning indicator and is not selectable (click / keyboard / hover are all ignored); update items to remove loading once the async work finishes. The demo below marks "Save" as loading for ~1.5s after you select it.

Loading menu items

Actions

Example

Async operation demo

Select an actionNothing selected

Example

API

Attributes

Attribute	Description	Type	Default
arrow	Whether to show the arrow pointing at the trigger (arrow="false" hides it; the skeleton is kept)	string	true
arrow-point-at-center	Pin the arrow to the panel center (by default the arrow follows the trigger's projection, so it still points at the trigger even after viewport-avoidance shifting)	boolean	—
auto-adjust-overflow	Auto-flip/avoid when there is not enough viewport space (auto-adjust-overflow="false" disables it; the panel may overflow the viewport)	string	true
close-on-scroll	Close the popover on page scroll (default repositions to follow; true closes on scroll)	boolean	—
disabled	Disable entirely: no trigger response	boolean	—
hide-on-click	Close after selecting an item (default true; false keeps it open for multi-select)	string	true
hover-delay	Open delay in ms on hover trigger (default 150)	—	—
hover-hide-delay	Close delay in ms on hover trigger (default 100)	—	—
items	Menu items JSON	string	[]
offset	Gap in px between popover and trigger (default 8)	—	—
open	Controlled display (boolean attribute; expands when present)	boolean	—
placement	Popup placement	string	bottom
split	Split button mode (boolean attribute): main button + arrow button; arrow opens the menu, main button fires oas-action	boolean	—
trigger	Trigger: click (default) / hover / focus; space-separated for multiple (e.g. "click hover")	string	click
value	Current selected value	string	—

Events

Event	Description
oas-action	Main button clicked in split mode, detail: { originalEvent }
oas-open-change	Popover open state changed, detail: { open: boolean } (including external setAttribute; controlled loop)
oas-select	An item was selected, detail: { value }

Slots

Name	Description
default	—

Clicking the trigger toggles visibility; clicking outside / pressing Esc / selecting an item closes it. The floating menu is an inner oas-menu (role="menu", leaf items menuitemradio, items with submenus menuitem) supporting cascading submenus and keyboard navigation.