Dropdown

Introduction

The Dropdown component displays a floating menu anchored to a trigger element. It supports both structured item arrays and flexible children composition, making it ideal for actions, navigation, filtering, and contextual menus. Dropdowns can be triggered by click, hover, or context menu, and support icons, dividers, disabled items, custom placement, and more.

Import

import { Dropdown } from '@odyssee/components';

LiveCodeEditor examples

Basic Dropdown

Code Éditable

Résultat

Dropdown with Dividers and Actions

Code Éditable

Résultat

Dropdown with Links

Code Éditable

Résultat

Placement Variants

Code Éditable

Résultat

Trigger Types

Code Éditable

Résultat

Disabled Items

Code Éditable

Résultat

User Account Menu Example

Code Éditable

Résultat

Props

Prop	Type	Default	Description
trigger	HTMLElement | string	—	The element or label that triggers the dropdown.
triggerClassName	string	—	Additional CSS classes for the trigger element.
items	Dropdown.Item[]	—	Array of menu items (see below for shape).
children	HTMLElement | HTMLElement[]	—	Alternative to items: custom dropdown content (use with Dropdown.Item and Dropdown.Divider).
placement	"top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" "left" | "left-start" | "left-end" | "right" | "right-start" | "right-end" | "auto"	"bottom"	Position of the dropdown relative to the trigger.
strategy	"fixed" | "absolute"	"fixed"	Positioning strategy for the dropdown menu.
offset	number	10	Offset (in px) between the trigger and the dropdown.
flip	boolean	true	Whether to flip the dropdown to stay in the viewport.
scope	"parent" | "window"	"parent"	Positioning scope for the dropdown.
triggerType	"click" | "hover" | "contextmenu"	"click"	How the dropdown is triggered.
autoClose	boolean | "inside" | "outside"	true	Controls auto-close behavior: on any click, only inside, or only outside.
closeOnSelect	boolean	true	Whether to close the dropdown when an item is selected.
hasAutofocus	boolean	true	Whether the dropdown menu should autofocus when opened.
isOpen	boolean | Signal<boolean>	—	Controlled open state (optional).
menuClassName	string	—	Additional CSS classes for the dropdown menu container.
onOpen	() => void	—	Callback fired when the dropdown opens.
onClose	() => void	—	Callback fired when the dropdown closes.
onSelect	(value: string | number) => void	—	Callback fired when an item with a value is selected.
className	string	—	Additional CSS classes for the dropdown container.
id	string	auto-generated	ID for the dropdown container.
...rest	—	—	Any other props are spread to the root container.

Dropdown.Item shape

• label: string | HTMLElement — The text or element for the menu item.
• value: string | number (optional) — Value passed to onSelect.
• icon: HTMLElement | string (optional) — Icon to display before the label.
• href: string (optional) — If provided, renders as a link.
• disabled: boolean (optional) — If true, the item is disabled.
• isDivider: boolean (optional) — If true, renders a divider instead of an item.
• onClick: () => void (optional) — Click handler for the item.
• className: string (optional) — Additional classes for the item.

Children composition

You can also use the Dropdown.Item and Dropdown.Divider subcomponents as children for full flexibility.

<Dropdown trigger="Menu">
  <Dropdown.Item>Newsletter</Dropdown.Item>
  <Dropdown.Item href="/purchases">Purchases</Dropdown.Item>
  <Dropdown.Divider />
  <Dropdown.Item icon={<Icon />}>Downloads</Dropdown.Item>
</Dropdown>

Implementation notes

• Dropdown supports both a structured items array and flexible children composition.
• The menu is rendered with Preline and Floating UI for positioning and accessibility.
• Supports custom triggers (button, avatar, etc.) and custom menu content.
• Placement, offset, flipping, and auto-close are fully configurable.
• Menu items can be links, buttons, disabled, have icons, or be dividers.
• The dropdown closes automatically on outside click, on select (if enabled), or Escape key.
• Keyboard navigation and ARIA roles are handled for accessibility.

Accessibility

• The dropdown menu uses role="menu" and proper ARIA attributes for assistive technologies.
• Keyboard navigation is supported: arrow keys to move, Enter/Space to select, Escape to close.
• The trigger element should be focusable (button, link, etc.).
• Menu closes on outside click or Escape key.
• Ensure all interactive items are accessible via keyboard and screen readers.

Best practices

• Use concise, clear labels for menu items.
• Group related actions with dividers for clarity.
• Use icons to visually distinguish actions when appropriate.
• Avoid placing destructive actions (like "Delete") next to frequent actions.
• For navigation, use href for menu items to ensure proper link semantics.
• Keep menus short and relevant to the context.

Related links

• ContextMenu documentation
• Popover documentation
• Tooltip documentation
• Odyssee Components documentation