Displays a menu to the user—such as a set of actions or functions—triggered by a button and allows a user to select one of them.

Dropdown follows the WAI-ARIA authoring practices for a menu button.

Import

import { Dropdown } from "@fuegokit/react";

Usage

Note: See styling for copy-paste examples.

<Dropdown>
  <Dropdown.Trigger>
    Reporting
    <AkChevronDownIcon />
  </Dropdown.Trigger>
  <Dropdown.Portal>
    <Dropdown.Content sideOffset={10}>
      <Dropdown.Item
        onSelect={() => alert("navigate to my application's SPA route")}

Features

Dropdown supports:

Controlled or uncontrolled behavior
Customization of side, alignment, offsets, and collision handling
Submenus and configurable reading direction
Items, labels, groups of items
Checkable items (single or multiple) with indeterminate states
Modal and non-modal modes
Optionally rendering a pointer arrow
Focus is fully managed
Full keyboard navigation
Typeahead support
Customizable dismissing and layering behavior

Styling

To apply styles to the Dropdown primitive, use Fuegokit React's themeGet function to access Fuegokit Tokens directly.

Component API

<StyledDropdown>
  <StyledDropdownTrigger>
    Reporting
    <AkChevronDownIcon />
  </StyledDropdownTrigger>
  <StyledDropdownPortal>
    <StyledDropdownContent>
      <StyledDropdownItem
        onSelect={() => alert("navigate to my application's SPA route")}

CSS

/react/src/GettingStartedPage/GlobalHeaderMenu.tsx

import { sx, Dropdown, themeGet } from "@fuegokit/react";

const slideUpAndFade = keyframes`
  from {
    opacity: 0;
    transform: translateY(2px);
  }
  to {
    opacity: 1;

Accessibility

Dropdown follows the WAI-ARIA authoring practices for a menu button.

Dropdown uses roving tabindex to manage focus movement among menu items.

When to use

Inside forms on full pages, modals, or side panels, whenever someone needs to filter or sort contents on a page or content area.

When not to use

If there are fewer than three options to choose from, use a radio button group instead.
If the experience is primarily form-based, use a Select when users are selecting from a list of options and will be submitting data.

Examples

Use the playground examples at Storybook to explore the props API in more granular detail.

Controlled

Toggle the checkbox to open the Dropdown with a controlled state variable. Focus is then trapped in the dropdown's content area.

Use keyboard arrow keys or mouse to select and activate an item.

Use the Escape key to close.

Open

/react/react-docs/examples/components/StyledDropdownExample.tsx

// local state for demonstrating both controlled and uncontrolled behavior
const [localOpen, setLocalOpen] = React.useState(false);

React.useEffect(() => {
  // Update local state to sync with the controlled behavior
  setLocalOpen(localOpen);
}, [localOpen]);

const onCheckboxChange = React.useCallback(() => {

Props

Contains all the parts of a Dropdown.

Name	Type	Default	Description
defaultOpen	boolean		The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.
open	boolean		The controlled open state of the dropdown menu. Must be used in conjunction with `onOpenChange`.
modal	string		The modality of the dropdown menu. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers.
dir	'ltr' \| 'rtl'	false	The reading direction of submenus when applicable. If omitted, inherits globally from DirectionProvider or assumes LTR (left-to-right) reading mode.

Events

Name	Type	Default	Description
onOpenChange	(open: boolean) => void	false	Event handler called when the open state of the dropdown menu changes.

Dropdown.Trigger

The button that toggles the dropdown menu. By default, the DropdownMenu.Content will position itself against the trigger.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Dropdown.Portal

A semantic HTML `<button>` element that allows a user to perform an action. The `<Combobox.Button>` accepts its contents as `children`. Other props such as `onPress` and `isDisabled` will be set by the Combobox.

Name	Type	Default	Description
forceMount	boolean	-	Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. If used on this part, it will be inherited by DropdownMenu.Content and DropdownMenu.SubContent respectively.
container	HTMLElement	-	Specify a container element to portal the content into.

Dropdown.Content

The component that pops out when the dropdown menu is open.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
loop	boolean	false	When `true`, keyboard navigation will loop from last item to first, and vice versa.
forceMount	boolean	false	Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. It inherits from `DropdownMenu.Portal`.
side	'top' \| 'right' \| 'bottom' \| 'left'	false	The preferred side of the trigger to render against when open. Will be reversed when collisions occur and `avoidCollisions` is enabled.
sideOffset	number	0	The distance in pixels from the trigger.
align	'start' \| 'center' \| 'end'	'center'	The preferred alignment against the trigger. May change when collisions occur.
alignOffset	number	0	An offset in pixels from the "start" or "end" alignment options.
avoidCollisions	boolean	true	When true, overrides the side andalign preferences to prevent collisions with boundary edges.
collisionBoundary	Element \| null \| Array<Element \| null>	[]	The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check.
collisionPadding	number \| Partial<Record<Side, number>>	0	The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }.
arrowPadding	number	0	The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners.
sticky	number	0	The sticky behavior on the align axis. "partial" will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless.
hideWhenDetached	boolean	false	Whether to hide the content when the trigger becomes fully occluded.

Events

Name	Type	Default	Description
onCloseAutoFocus	(event: Event) => void	false	Event handler called when focus moves to the trigger after closing. It can be prevented by calling `event.preventDefault`.
onEscapeKeyDown	(event: KeyboardEvent) => void	false	Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`.
onPointerDownOutside	(event: KeyboardEvent) => void	false	Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`.
onFocuseOutside	(event: FocusOutsideEvent) => void	false	Event handler called when focus moves outside the bounds of the component. It can be prevented by calling `event.preventDefault`.
onInteractOutside	(event: PointerDownOutsideEvent \| FocusOutsideEvent) => void	false	Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling `event.preventDefault`.

Dropdown.Arrow

An optional arrow element to render alongside the dropdown menu. This can be used to help visually link the trigger with the DropdownMenu.Content. Must be rendered inside DropdownMenu.Content.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
width	number	10	The width of the arrow in pixels.
width	number	5	The height of the arrow in pixels.

Dropdown.Item

The component that contains the dropdown menu items.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
disabled	boolean	10	When `true`, prevents the user from interacting with the item.

Events

Name	Type	Default	Description
onSelect	(event: Event) => void	-	Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the dropdown menu from closing when selecting that item.
textValue	string	-	Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside.

Dropdown.Group

Used to group multiple DropdownMenu.Items.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Dropdown.Label

Used to render a label. It won't be focusable using arrow keys.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Dropdown.CheckboxItem

An item that can be controlled and rendered like a checkbox.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
checked	boolean \| 'indeterminate'	false	The controlled checked state of the item. Must be used in conjunction with onCheckedChange.
disabled	boolean	false	When true, prevents the user from interacting with the item.
textValue	string	false	Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside.

Events

Name	Type	Default	Description
onCheckedChange	(checked: boolean) => void	false	Event handler called when the checked state changes.
onSelect	(event: Event) => void	false	Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the dropdown menu from closing when selecting that item.

Dropdown.RadioGroup

Used to group multiple DropdownMenu.RadioItems.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
value	string	-	The value of the selected item in the group.

Events

Name	Type	Default	Description
onValueChange	(value: string) => void	false	Event handler called when the value changes.

Dropdown.RadioItem

An item that can be controlled and rendered like a radio.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
value*	string	-	The unique value of the item.
disabled	boolean		When true, prevents the user from interacting with the item.
textValue	string	-	Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item. Use this when the content is complex, or you have non-textual content inside.

Events

Name	Type	Default	Description
onSelect	(event: Event) => void	-	Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the dropdown menu from closing when selecting that item.

Dropdown.ItemIndicator

Renders when the parent DropdownMenu.CheckboxItem or DropdownMenu.RadioItem is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
forceMount	boolean	-	Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

Dropdown.Separator

Used to visually separate items in the dropdown menu.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.

Dropdown.Sub

Contains all the parts of a submenu.

Name	Type	Default	Description
defaultOpen	boolean	-	The open state of the submenu when it is initially rendered. Use when you do not need to control its open state.
open	boolean	-	The controlled open state of the submenu. Must be used in conjunction with `onOpenChange`.

Events

Name	Type	Default	Description
onOpenChange	(open: boolean) => void	-	Event handler called when the open state of the submenu changes.

Dropdown.SubTrigger

An item that opens a submenu. Must be rendered inside DropdownMenu.Sub.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
disabled	boolean	-	When true, prevents the user from interacting with the item.
textValue	string	-	Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside.

Dropdown.SubContent

The component that pops out when a submenu is open. Must be rendered inside DropdownMenu.Sub.

Name	Type	Default	Description
asChild	boolean	false	Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.
loop	boolean	false	When `true`, keyboard navigation will loop from last item to first, and vice versa.
forceMount	boolean	false	Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. It inherits from `DropdownMenu.Portal`.
sideOffset	number	0	The distance in pixels from the trigger.
alignOffset	number	0	An offset in pixels from the "start" or "end" alignment options.
avoidCollisions	boolean	true	When true, overrides the side andalign preferences to prevent collisions with boundary edges.
collisionBoundary	Element \| null \| Array<Element \| null>	[]	The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check.
collisionPadding	number \| Partial<Record<Side, number>>	0	The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }.
arrowPadding	number	0	The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners.
sticky	number	0	The sticky behavior on the align axis. "partial" will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless.
hideWhenDetached	boolean	false	Whether to hide the content when the trigger becomes fully occluded.

Events

Name	Type	Default	Description
onEscapeKeyDown	(event: KeyboardEvent) => void	false	Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`.
onPointerDownOutside	(event: KeyboardEvent) => void	false	Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`.
onFocuseOutside	(event: FocusOutsideEvent) => void	false	Event handler called when focus moves outside the bounds of the component. It can be prevented by calling `event.preventDefault`.
onInteractOutside	(event: PointerDownOutsideEvent \| FocusOutsideEvent) => void	false	Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling `event.preventDefault`.

Keyboard interactions

Key	Description
Space	When focus is on `Dropdown.Trigger`, opens the select and focuses the first item. When focus is on an item, activates the focused item. When focus is on an itme, activates the focused item.
Enter	When focus is on `Dropdown.Trigger`, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item.
ArrowDown	When focus is on `Dropdown.Trigger`, opens the dropdown menu. When focus is on an item, moves focus to the next item.
ArrowUp	When focus is on an item, moves focus to the previous item.
ArrowRight, ArrowLeft	When focus is on `Dropdown.SubTrigger`, opens or closes the submenu depending on reading direction.
Esc	Closes the dropdown and moves focus to `Dropdown.Trigger`.