import { 
  DropdownMenu, 
  DropdownMenuTrigger, 
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuTriggerButton,
  DropdownMenuCheckboxItem,
  DropdownMenuFooter,
  DropdownMenuSub,
  DropdownMenuSubTrigger,
} from '@customerio/pluma-components/react';

Usage

A DropdownMenu is composed of several components:

DropdownMenu - the root component, which sets up the context, state and interactions
DropdownMenuTrigger - the element that triggers the dropdown menu to show
DropdownMenuTriggerButton - a Button component that acts as a trigger for the dropdown menu
DropdownMenuContent - the container for menu items
DropdownMenuGroup - optional component to organize items into labeled groups
DropdownMenuItem - individual selectable items in the menu
DropdownMenuCheckboxItem - selectable items with a checkbox state
DropdownMenuFooter - component to display footer content at the bottom of a dropdown menu
DropdownMenuSub - wrapper component for nested submenus
DropdownMenuSubTrigger - trigger component for nested submenus

Basic example

<DropdownMenu>
  <DropdownMenuTrigger>Actions</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem onClick={() => console.log('Edit')}>
      Edit
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Duplicate')}>
      Duplicate
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Delete')} isDanger={true}>
      Delete
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

With groups

You can organize related menu items using the DropdownMenuGroup component:

<DropdownMenu>
  <DropdownMenuTrigger>Actions</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuGroup label="Edit options">
      <DropdownMenuItem onClick={() => console.log('Edit')}>
        Edit
      </DropdownMenuItem>
      <DropdownMenuItem onClick={() => console.log('Duplicate')}>
        Duplicate
      </DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuGroup label="Danger zone">
      <DropdownMenuItem onClick={() => console.log('Delete')} isDanger={true}>
        Delete
      </DropdownMenuItem>
    </DropdownMenuGroup>
  </DropdownMenuContent>
</DropdownMenu>

With icons

Menu items can include icons for better visual recognition:

<DropdownMenu>
  <DropdownMenuTrigger>Actions</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem onClick={() => console.log('Edit')} icon="edit">
      Edit
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Duplicate')} icon="copy-to-clipboard">
      Duplicate
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Delete')} isDanger={true} icon="delete-trash">
      Delete
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

With descriptions

Menu items can include descriptions to provide additional context or explanation:

<DropdownMenu>
  <DropdownMenuTrigger>Options with Description</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem 
      onClick={() => console.log('Analyze')} 
      icon="activity"
      description="View detailed metrics and insights"
    >
      Analyze Data
    </DropdownMenuItem>
    <DropdownMenuItem 
      onClick={() => console.log('Export')} 
      icon="download"
      description="Download data in CSV or Excel format"
    >
      Export Results
    </DropdownMenuItem>
    <DropdownMenuItem 
      onClick={() => console.log('Delete')} 
      isDanger={true} 
      icon="delete-trash"
      description="Permanently remove this data set"
    >
      Delete Data
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

With tooltips

Menu items can show tooltips when hovering over them, providing additional information or context. The most common use case is to show a tooltip when the item is disabled.

<DropdownMenu>
  <DropdownMenuTrigger>Items with Tooltips</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem 
      onClick={() => console.log('Edit')} 
      icon="edit"
      tooltip="Edit this item's properties"
    >
      Edit
    </DropdownMenuItem>
    <DropdownMenuItem 
      onClick={() => console.log('Share')} 
      icon="copy-to"
      tooltip="Share with team members"
    >
      Share
    </DropdownMenuItem>
    <DropdownMenuItem 
      onClick={() => console.log('Delete')} 
      isDanger={true} 
      icon="delete-trash"
      tooltip="Delete this item permanently"
    >
      Delete
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Checkbox items

Checkbox items allow users to toggle state within a dropdown menu:

import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuCheckboxItem,
} from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
  const [checkedItems, setCheckedItems] = useState({
    option1: false,
    option2: true,
  });

  const handleCheckedChange = (item, checked) => {
    setCheckedItems(prev => ({
      ...prev,
      [item]: checked,
    }));
  };


  return (
    <DropdownMenu>
      <DropdownMenuTrigger>Options</DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuGroup label="Choose options">
          <DropdownMenuCheckboxItem 
            isChecked={checkedItems.option1}
            onCheckedChange={(checked) => handleCheckedChange('option1', checked)}
          >
            Option 1
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem 
            isChecked={checkedItems.option2}
            onCheckedChange={(checked) => handleCheckedChange('option2', checked)}
          >
            Option 2
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem 
            isChecked={false}
            onCheckedChange={() => {}}
            isDisabled={true}
          >
            Option 3 (Disabled)
          </DropdownMenuCheckboxItem>
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

Disabled items

Menu items can be disabled to indicate they're not available:

<DropdownMenu>
  <DropdownMenuTrigger>Actions</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem onClick={() => console.log('Edit')}>
      Edit
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Duplicate')} isDisabled={true}>
      Duplicate (Disabled)
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Delete')} isDanger={true} isDisabled={true}>
      Delete (Disabled)
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

By default, clicking a menu item will close the dropdown. You can prevent this behavior by setting shouldCloseOnClick={false}. This is useful when the user might want to select multiple items or perform actions without closing the menu.

<DropdownMenu>
  <DropdownMenuTrigger>Actions</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem 
      onClick={() => console.log('Copy to clipboard')} 
      shouldCloseOnClick={false}
      icon="copy-to-clipboard"
    >
      Copy to clipboard (stays open)
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Edit')}>
      Edit (closes dropdown)
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Danger items

The isDanger prop can be used to style menu items with a red color, indicating destructive or risky actions:

<DropdownMenu>
  <DropdownMenuTrigger>Actions</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem onClick={() => console.log('Edit')}>
      Edit
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Delete')} isDanger={true}>
      Delete
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Link items

Menu items can be rendered as links by providing the href attribute. This is useful for navigation or opening resources:

<DropdownMenu>
  <DropdownMenuTrigger>Navigation</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem href="/dashboard">
      Dashboard
    </DropdownMenuItem>
    <DropdownMenuItem href="/settings" icon="workspace-settings">
      Settings
    </DropdownMenuItem>
    <DropdownMenuItem href="https://docs.customer.io" isExternal={true} icon="copy-to">
      Documentation
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Using a button as trigger

The DropdownMenuTriggerButton component is a convenient way to use a Button as the trigger for your dropdown menu. It supports all Button props (variant, size, icon, etc.).

<DropdownMenu>
  <DropdownMenuTriggerButton variant="primary" icon="chevron-down" iconPosition="trailing">
    Open Menu
  </DropdownMenuTriggerButton>
  <DropdownMenuContent>
    <DropdownMenuItem onClick={() => console.log('Option 1')}>
      Option 1
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Option 2')}>
      Option 2
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Custom trigger

By default, DropdownMenuTrigger will render an unstyled button tag. It is important to render an element that is focusable, and that indicates it can be clicked.

The DropdownMenu component exposes Floating UI props, which can be used to attach trigger interactions to any element.

<DropdownMenu>
  {(context) => (
    <Button
      ref={context.reference.setReference}
      {...context.reference.getReferenceProps()}
    >
      Click me
    </Button>
  )}

  <DropdownMenuContent>
    <DropdownMenuItem onClick={() => console.log('Option 1')}>
      Option 1
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Option 2')}>
      Option 2
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Placement

The dropdown menu can be positioned relative to the trigger using the placement prop:

<Box display="flex" gap="500">
  <DropdownMenu placement="bottom-start">
    <DropdownMenuTrigger>Bottom Start</DropdownMenuTrigger>
    <DropdownMenuContent>
      <DropdownMenuItem onClick={() => console.log('Option 1')}>Option 1</DropdownMenuItem>
      <DropdownMenuItem onClick={() => console.log('Option 2')}>Option 2</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>

  <DropdownMenu placement="bottom-end">
    <DropdownMenuTrigger>Bottom End</DropdownMenuTrigger>
    <DropdownMenuContent>
      <DropdownMenuItem onClick={() => console.log('Option 1')}>Option 1</DropdownMenuItem>
      <DropdownMenuItem onClick={() => console.log('Option 2')}>Option 2</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>

  <DropdownMenu placement="top">
    <DropdownMenuTrigger>Top</DropdownMenuTrigger>
    <DropdownMenuContent>
      <DropdownMenuItem onClick={() => console.log('Option 1')}>Option 1</DropdownMenuItem>
      <DropdownMenuItem onClick={() => console.log('Option 2')}>Option 2</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</Box>

With footer

You can add a footer to the dropdown menu using the DropdownMenuFooter component. The footer must be placed directly inside the DropdownMenuContent component:

<DropdownMenu>
  <DropdownMenuTrigger>Actions with Footer</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem onClick={() => console.log('Edit')} icon="edit">
      Edit
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Duplicate')} icon="copy-to-clipboard">
      Duplicate
    </DropdownMenuItem>
    <DropdownMenuGroup label="More options">
      <DropdownMenuItem onClick={() => console.log('Option 1')}>
        Option 1
      </DropdownMenuItem>
      <DropdownMenuItem onClick={() => console.log('Option 2')}>
        Option 2
      </DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuFooter>
      Footer content
    </DropdownMenuFooter>
  </DropdownMenuContent>
</DropdownMenu>

Nested menus

Dropdown menus can contain nested submenus for organizing hierarchical actions or options. Nested menus use the DropdownMenuSub component to wrap the nested content, and the DropdownMenuSubTrigger component which is the trigger for the submenu, as well as a menu item in its parent menu.

import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSub,
  DropdownMenuSubTrigger,
} from '@customerio/pluma-components/react';

export default function Example() {
  return (
    <DropdownMenu>
      <DropdownMenuTriggerButton variant="primary" icon="chevron-down" iconPosition="trailing">
        Open Menu
      </DropdownMenuTriggerButton>

      <DropdownMenuContent>
        <DropdownMenuItem onClick={() => console.log('Edit')}>
          Edit
        </DropdownMenuItem>
        <DropdownMenuItem onClick={() => console.log('Duplicate')}>
          Duplicate
        </DropdownMenuItem>
        
        <DropdownMenuSub>
          <DropdownMenuSubTrigger>More Options</DropdownMenuSubTrigger>
          
          <DropdownMenuContent>
            <DropdownMenuItem onClick={() => console.log('Export')}>
              Export
            </DropdownMenuItem>
            <DropdownMenuItem onClick={() => console.log('Archive')}>
              Archive
            </DropdownMenuItem>
            <DropdownMenuItem onClick={() => console.log('Share')}>
              Share
            </DropdownMenuItem>
            
            <DropdownMenuSub>
              <DropdownMenuSubTrigger>Advanced</DropdownMenuSubTrigger>
              
              <DropdownMenuContent>
                <DropdownMenuItem onClick={() => console.log('Settings')}>
                  Settings
                </DropdownMenuItem>
                <DropdownMenuItem onClick={() => console.log('Permissions')}>
                  Permissions
                </DropdownMenuItem>
                <DropdownMenuItem onClick={() => console.log('Analytics')} isDisabled={true} tooltip="Coming Soon">
                  Analytics
                </DropdownMenuItem>
              </DropdownMenuContent>
            </DropdownMenuSub>
          </DropdownMenuContent>
        </DropdownMenuSub>

        <DropdownMenuSub>
          <DropdownMenuSubTrigger
            isDisabled={true} 
            tooltip="You don't have permission to perform these actions"
          >
            Custom actions
          </DropdownMenuSubTrigger>
          
          <DropdownMenuContent>
            <DropdownMenuItem onClick={() => console.log('Clone')}>
              Clone
            </DropdownMenuItem>
            <DropdownMenuItem onClick={() => console.log('Sync')}>
              Sync
            </DropdownMenuItem>
          </DropdownMenuContent>
        </DropdownMenuSub>
        
        <DropdownMenuItem onClick={() => console.log('Delete')} isDanger={true}>
          Delete
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

Accessibility

The DropdownMenu component follows the ARIA menu button pattern and includes the following accessibility features:

Menu role semantics (role="menu", role="menuitem")
Keyboard navigation between menu items with arrow keys
Auto-focusing the first menu item when opened
Focus management
Screen reader announcements for menu state changes

The component supports focus trap functionality via the shouldTrapFocus prop, which keeps focus within the menu when it's open:

<DropdownMenu shouldTrapFocus={true}>
  <DropdownMenuTrigger>Trapped Focus</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem onClick={() => console.log('Option 1')}>
      Option 1
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Option 2')}>
      Option 2
    </DropdownMenuItem>
    <DropdownMenuItem onClick={() => console.log('Option 3')}>
      Option 3
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

More focus management options are available via the following props:

API

`PlumaDropdownMenu` `extends Box`

`additionalMiddleware` `{ name: string; options?: any; fn: (state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => Promisable<MiddlewareReturn>; }[] | undefined`

Additional middleware to apply to Floating UI, for example custom middleware for more control. These will be applied after the default middleware.

`animationTransitionDuration` `number | undefined`

Default:125

The duration (in ms) for the popover animation.

`defaultIsOpen` `boolean | undefined`

Whether the popover should be open initially

`floatingPluginOptions` { click?: { enabled?: boolean | undefined; event?: "click" | "mousedown" | undefined; toggle?: boolean | undefined; ignoreMouse?: boolean | undefined; keyboardHandlers?: boolean | undefined; } | undefined; hover?: { enabled?: boolean | undefined; mouseOnly?: boolean | undefined; delay?: number | Partial<{ open: number; close: number; }> | undefined; restMs?: number | undefined; move?: boolean | undefined; handleClose?: any; } | undefined; focus?: { enabled?: boolean | undefined; visibleOnly?: boolean | undefined; } | undefined; dismiss?: { enabled?: boolean | undefined; escapeKey?: boolean | undefined; referencePress?: boolean | undefined; referencePressEvent?: "click" | "mousedown" | "pointerdown" | undefined; outsidePress?: boolean | ((event: MouseEvent) => boolean) | undefined; outsidePressEvent?: "click" | "mousedown" | "pointerdown" | undefined; ancestorScroll?: boolean | undefined; bubbles?: boolean | { escapeKey?: boolean | undefined; outsidePress?: boolean | undefined; } | undefined; capture?: boolean | { escapeKey?: boolean | undefined; outsidePress?: boolean | undefined; } | undefined; } | undefined; role?: { enabled?: boolean | undefined; role?: "grid" | "listbox" | "menu" | "tooltip" | "dialog" | "label" | "select" | "tree" | "alertdialog" | "combobox" | undefined; } | undefined; } | undefined

Additional options to pass to Floating UI's plugins/hooks.

`focusOrder` `("content" | "reference" | "floating")[] | undefined`

Default:['content']

The order in which focus should be moved when navigating through the popover. See Floating UI for more details.

`initialFocus` `number | HTMLElement | undefined`

Default:0

Which element to initially focus when the popover is opened. Can be a number (a tabbable index as specified by focusOrder) or an HTMLElement. See Floating UI for more details.

`isDisabled` `boolean | undefined`

Default:false

Whether the popover should be disabled. Can be used to conditionally enable/disable a popover depending on state.

`isDraggable` `boolean | undefined`

Default:false

Whether the popover should be draggable.

`isFocusManagerDisabled` `boolean | undefined`

Default:false

Whether the focus manager (for the opened popover) should be disabled entirely. See Floating UI for more details.

`isOpen` `boolean | undefined`

Whether the popover should be open. Only use this along with onOpenChange if you want to control the state of the popover

`listNavigationOptions` `{ activeIndex?: number | null | undefined; onNavigate?: ((activeIndex: number | null) => void) | undefined; loop?: boolean | undefined; virtual?: boolean | undefined; allowEscape?: boolean | undefined; focusItemOnHover?: boolean | undefined; focusItemOnOpen?: boolean | undefined; } | undefined`

Additional options to pass to Floating UI's list navigation plugin.

`middlewareOptions` { arrow?: Partial<{ padding?: Padding | undefined; element: Element; }> | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => Partial<{ padding?: Padding | undefined; element: Element; }>) | undefined; offset?: Partial<{ mainAxis: number; crossAxis: number; alignmentAxis: number | null; }> | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => Partial<{ mainAxis: number; crossAxis: number; alignmentAxis: number | null; }>) | undefined; flip?: { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; fallbackPlacements?: Placement[] | undefined; fallbackStrategy?: "initialPlacement" | "bestFit" | undefined; fallbackAxisSideDirection?: "none" | "end" | "start" | undefined; flipAlignment?: boolean | undefined; boundary?: Boundary | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; fallbackPlacements?: Placement[] | undefined; fallbackStrategy?: "initialPlacement" | "bestFit" | undefined; fallbackAxisSideDirection?: "none" | "end" | "start" | undefined; flipAlignment?: boolean | undefined; boundary?: Boundary | undefined; }) | undefined; shift?: { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; limiter?: { fn: (state: MiddlewareState) => Coords; options?: any; } | undefined; boundary?: Boundary | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; mainAxis?: boolean | undefined; crossAxis?: boolean | undefined; limiter?: { fn: (state: MiddlewareState) => Coords; options?: any; } | undefined; boundary?: Boundary | undefined; }) | undefined; hide?: { padding?: Padding | undefined; strategy?: "referenceHidden" | "escaped" | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; strategy?: "referenceHidden" | "escaped" | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; }) | undefined; size?: { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; apply?: ((args: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; } & { availableWidth: number; availableHeight: number; }) => Promisable<void>) | undefined; } | ((state: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; }) => { padding?: Padding | undefined; rootBoundary?: RootBoundary | undefined; elementContext?: ElementContext | undefined; altBoundary?: boolean | undefined; boundary?: Boundary | undefined; apply?: ((args: { x: number; y: number; placement: Placement; strategy: Strategy; initialPlacement: Placement; middlewareData: MiddlewareData; rects: ElementRects; platform: Platform; elements: Elements; } & { availableWidth: number; availableHeight: number; }) => Promisable<void>) | undefined; }) | undefined; } | undefined

Additional options to pass into Floating UI middleware

`onOpenChange` `((isOpen: boolean, event?: Event | undefined, reason?: "focus" | "hover" | "outside-press" | "escape-key" | "ancestor-scroll" | "reference-press" | "click" | "list-navigation" | "safe-polygon" | undefined) => void) | undefined`

Called when the open state of the popover is changing

`placement` `Placement | undefined`

Where the popover should be placed in relation to the trigger

`shouldCloseOnFocusOut` `boolean | undefined`

Default:true

Whether focusout event listeners are attached to the trigger and popover, to close the popover when focus moves outside of it. See Floating UI for more details.

`shouldNavigateList` `boolean | undefined`

Default:false

Whether the popover should navigate through a list of items when the arrow keys are pressed. See Floating UI for more details.

`shouldRenderFocusGuards` `boolean | undefined`

Default:true

Whether the focus guards are rendered by the focus manager. See Floating UI for more details.

`shouldRestrictSize` `boolean | { width?: boolean | undefined; height?: boolean | undefined; } | undefined`

Default:true

Whether the popover content's max width and/or max height should be restricted using the Floating UI size middleware.

By default, this is disabled so that the dropdown menu is not restricted

`shouldReturnFocus` `boolean | undefined`

Default:true

Whether focus should be returned to the trigger when the popover is closed. See Floating UI for more details.

`shouldShowVisuallyHiddenDismiss` `boolean | undefined`

Default:false

Whether visually hidden close buttons are rendered before and after the popover. See Floating UI for more details.

`shouldTrapFocus` `boolean | undefined`

Default:false

If the popover contains interactive elements, the dialog pattern should be applied. Enable shouldTrapFocus to ensure focus is kept within the popover while it's open. See Floating UI for more details.

`shouldTriggerOnClick` `boolean | undefined`

Default:true

Whether the popover should open when the trigger is clicked. This is the recommended default.

`shouldTriggerOnFocus` `boolean | undefined`

Default:false

Whether the popover should open when the trigger is focused. Defaults to true when shouldTriggerOnHover is true.

`shouldTriggerOnHover` `boolean | undefined`

Default:false

Whether the popover should open when the trigger is hovered. Only use if absolutely necessary, as Popovers are meant to be triggered by clicks.

`strategy` `Strategy | undefined`

The position CSS property to use on the floating element

`unsafe_popoverClassName` `string | undefined`

Additional classes to apply on the popover component (the floating element, not the trigger). Should only be used as a last resort

`unsafe_popoverContentClassName` `string | undefined`

Additional classes to apply on the popover content component. Should only be used as a last resort

`unsafe_popoverStyle` `Record<string, unknown> | undefined`

Additional inline styles to apply on the popover component (the floating element, not the trigger). Should only be used as a last resort

`unsafe_registerNodeId` `((id: string) => void) | undefined`

An internal function to pass the Floating UI nodeId up to a parent if necessary.

`withTypeahead` `boolean | undefined`

Default:false

Whether "typeahead" functionality should be enabled, which focuses items while typing. See Floating UI for more details. Enabled by default when shouldNavigateList is true.

`PlumaDropdownMenuTrigger` `extends Box`

`PlumaDropdownMenuContent` `extends Box`

`PlumaDropdownMenuGroup` `extends Box`

`label` `string | undefined`

An option label for the group. If not provided, the group won't render a header, but will still render a divider to separate action items from other groups.

`PlumaDropdownMenuItem` `extends Box`

`description` `string | null | undefined`

Optional description text to display below the menu item

`href` `string | undefined`

The URL for the link, if the item should render as a link instead of a button

`icon` `IconName | null | undefined`

Optional icon to display alongside the menu item text

`isDanger` `boolean | undefined`

Whether the item should be displayed with critical/danger styling

`isDisabled` `boolean | undefined`

Whether the item is disabled

`isExternal` `boolean | undefined`

Whether the link is external. When this flag is true, an a tag will be used, and target="_blank" rel="noopener noreferrer" will be added automatically

`isTrigger` `boolean | undefined`

Whether this item is also a trigger for another sub-menu.

`onClick` `((event?: EventType | undefined) => void) | undefined`

Function called when the item is selected

`replace` `boolean | undefined`

This is passed into the provider's linkComponent when used with href. It can be used by the link component implementation to handle replaceState instead of pushState

`shouldCloseOnClick` `boolean | undefined`

Default:true

Whether clicking the item should close the popover

`trailingIcon` `IconName | null | undefined`

Optional icon to display on the trailing side of the menu item. Typically used for a sub-menu trigger indicator (e.g. a right chevron).

`withSafeExternalAttributes` `boolean | undefined`

Default:true

Whether to add safe external attributes (target="_blank" rel="noopener noreferrer") for external links. This can be turned off for special cases like mailto: links

`PlumaDropdownMenuTriggerButton` `extends Button`

`PlumaDropdownMenuCheckboxItem` `extends Box`

`description` `string | null | undefined`

Optional description text to display below the menu item

`href` `string | undefined`

The URL for the link, if the item should render as a link instead of a button

`isChecked` `boolean` (required)

Whether the checkbox is checked

`isDanger` `boolean | undefined`

Whether the item should be displayed with critical/danger styling

`isDisabled` `boolean | undefined`

Whether the item is disabled

`isExternal` `boolean | undefined`

Whether the link is external. When this flag is true, an a tag will be used, and target="_blank" rel="noopener noreferrer" will be added automatically

`isTrigger` `boolean | undefined`

Whether this item is also a trigger for another sub-menu.

`onCheckedChange` `(checked: boolean) => void` (required)

Callback to be called when the checkbox is checked or unchecked

`onClick` `((event?: NativeOnClickEventArgType | undefined) => void) | undefined`

Function called when the item is selected

`replace` `boolean | undefined`

This is passed into the provider's linkComponent when used with href. It can be used by the link component implementation to handle replaceState instead of pushState

`shouldCloseOnClick` `boolean | undefined`

Default:true

Whether clicking the item should close the popover

`trailingIcon` `IconName | null | undefined`

Optional icon to display on the trailing side of the menu item. Typically used for a sub-menu trigger indicator (e.g. a right chevron).

`withSafeExternalAttributes` `boolean | undefined`

Default:true

Whether to add safe external attributes (target="_blank" rel="noopener noreferrer") for external links. This can be turned off for special cases like mailto: links

DropdownMenu

PlumaDropdownMenu extends Box

animationTransitionDuration number | undefined

defaultIsOpen boolean | undefined

focusOrder ("content" | "reference" | "floating")[] | undefined

initialFocus number | HTMLElement | undefined

isDisabled boolean | undefined

isDraggable boolean | undefined

isFocusManagerDisabled boolean | undefined

isOpen boolean | undefined

onOpenChange ((isOpen: boolean, event?: Event | undefined, reason?: "focus" | "hover" | "outside-press" | "escape-key" | "ancestor-scroll" | "reference-press" | "click" | "list-navigation" | "safe-polygon" | undefined) => void) | undefined

placement Placement | undefined

shouldCloseOnFocusOut boolean | undefined

shouldNavigateList boolean | undefined

shouldRenderFocusGuards boolean | undefined

shouldRestrictSize boolean | { width?: boolean | undefined; height?: boolean | undefined; } | undefined

shouldReturnFocus boolean | undefined

shouldShowVisuallyHiddenDismiss boolean | undefined

shouldTrapFocus boolean | undefined

shouldTriggerOnClick boolean | undefined

shouldTriggerOnFocus boolean | undefined

shouldTriggerOnHover boolean | undefined

strategy Strategy | undefined

unsafe_popoverClassName string | undefined

unsafe_popoverContentClassName string | undefined

unsafe_popoverStyle Record<string, unknown> | undefined

unsafe_registerNodeId ((id: string) => void) | undefined

withTypeahead boolean | undefined

PlumaDropdownMenuTrigger extends Box

PlumaDropdownMenuContent extends Box

PlumaDropdownMenuGroup extends Box

label string | undefined

PlumaDropdownMenuItem extends Box

description string | null | undefined

href string | undefined

icon IconName | null | undefined

isDanger boolean | undefined

isDisabled boolean | undefined

isExternal boolean | undefined

isTrigger boolean | undefined

onClick ((event?: EventType | undefined) => void) | undefined

replace boolean | undefined

shouldCloseOnClick boolean | undefined

tooltip string | null | undefined

trailingIcon IconName | null | undefined

withSafeExternalAttributes boolean | undefined

PlumaDropdownMenuTriggerButton extends Button

PlumaDropdownMenuCheckboxItem extends Box

description string | null | undefined

href string | undefined

isChecked boolean (required)

isDanger boolean | undefined

isDisabled boolean | undefined

isExternal boolean | undefined

isTrigger boolean | undefined

onCheckedChange (checked: boolean) => void (required)

onClick ((event?: NativeOnClickEventArgType | undefined) => void) | undefined

replace boolean | undefined

shouldCloseOnClick boolean | undefined

tooltip string | null | undefined

trailingIcon IconName | null | undefined

withSafeExternalAttributes boolean | undefined

PlumaDropdownMenuFooter extends Box

PlumaDropdownMenuSubTrigger extends Box

href string | undefined

isDisabled boolean | undefined

isExternal boolean | undefined

onClick ((event?: EventType | undefined) => void) | undefined

replace boolean | undefined

shouldCloseOnClick boolean | undefined

withSafeExternalAttributes boolean | undefined

PlumaDropdownMenuSub extends Box

On this page

`PlumaDropdownMenu` `extends Box`

`animationTransitionDuration` `number | undefined`

`defaultIsOpen` `boolean | undefined`

`focusOrder` `("content" | "reference" | "floating")[] | undefined`

`initialFocus` `number | HTMLElement | undefined`

`isDisabled` `boolean | undefined`

`isDraggable` `boolean | undefined`

`isFocusManagerDisabled` `boolean | undefined`

`isOpen` `boolean | undefined`

`onOpenChange` `((isOpen: boolean, event?: Event | undefined, reason?: "focus" | "hover" | "outside-press" | "escape-key" | "ancestor-scroll" | "reference-press" | "click" | "list-navigation" | "safe-polygon" | undefined) => void) | undefined`

`placement` `Placement | undefined`

`shouldCloseOnFocusOut` `boolean | undefined`

`shouldNavigateList` `boolean | undefined`

`shouldRenderFocusGuards` `boolean | undefined`

`shouldRestrictSize` `boolean | { width?: boolean | undefined; height?: boolean | undefined; } | undefined`

`shouldReturnFocus` `boolean | undefined`

`shouldShowVisuallyHiddenDismiss` `boolean | undefined`

`shouldTrapFocus` `boolean | undefined`

`shouldTriggerOnClick` `boolean | undefined`

`shouldTriggerOnFocus` `boolean | undefined`

`shouldTriggerOnHover` `boolean | undefined`

`strategy` `Strategy | undefined`

`unsafe_popoverClassName` `string | undefined`

`unsafe_popoverContentClassName` `string | undefined`

`unsafe_popoverStyle` `Record<string, unknown> | undefined`

`unsafe_registerNodeId` `((id: string) => void) | undefined`

`withTypeahead` `boolean | undefined`

`PlumaDropdownMenuTrigger` `extends Box`

`PlumaDropdownMenuContent` `extends Box`

`PlumaDropdownMenuGroup` `extends Box`

`label` `string | undefined`

`PlumaDropdownMenuItem` `extends Box`

`description` `string | null | undefined`

`href` `string | undefined`

`icon` `IconName | null | undefined`

`isDanger` `boolean | undefined`

`isDisabled` `boolean | undefined`

`isExternal` `boolean | undefined`

`isTrigger` `boolean | undefined`

`onClick` `((event?: EventType | undefined) => void) | undefined`

`replace` `boolean | undefined`

`shouldCloseOnClick` `boolean | undefined`

`tooltip` `string | null | undefined`

`trailingIcon` `IconName | null | undefined`

`withSafeExternalAttributes` `boolean | undefined`

`PlumaDropdownMenuTriggerButton` `extends Button`

`PlumaDropdownMenuCheckboxItem` `extends Box`

`description` `string | null | undefined`

`href` `string | undefined`

`isChecked` `boolean` (required)

`isDanger` `boolean | undefined`

`isDisabled` `boolean | undefined`

`isExternal` `boolean | undefined`

`isTrigger` `boolean | undefined`

`onCheckedChange` `(checked: boolean) => void` (required)

`onClick` `((event?: NativeOnClickEventArgType | undefined) => void) | undefined`

`replace` `boolean | undefined`

`shouldCloseOnClick` `boolean | undefined`

`tooltip` `string | null | undefined`

`trailingIcon` `IconName | null | undefined`

`withSafeExternalAttributes` `boolean | undefined`

`PlumaDropdownMenuFooter` `extends Box`

`PlumaDropdownMenuSubTrigger` `extends Box`

`href` `string | undefined`

`isDisabled` `boolean | undefined`

`isExternal` `boolean | undefined`

`onClick` `((event?: EventType | undefined) => void) | undefined`

`replace` `boolean | undefined`

`shouldCloseOnClick` `boolean | undefined`

`withSafeExternalAttributes` `boolean | undefined`

`PlumaDropdownMenuSub` `extends Box`