Dropdown - Docs - Artefact

Dropdown

Overlays

Auto-interactive

Introduction

A list of actions or options that appears when triggered. Supports custom placements with automatic viewport-overflow flipping, an optional arrow with center-pointing geometry, checkbox/radio/group items, cascading submenus, and click / hover / context menu trigger modes.

Usage

Basic Dropdown

import { Dropdown, Button } from "../components/ui";

export default function MyPage() {
  return (
    <Dropdown
      trigger={<Button>Open Dropdown</Button>}
      items={[
        { type: "item", label: "Edit", value: "edit" },
        { type: "separator" },
        { type: "checkbox", label: "Bold", value: "bold", checked: true },
        {
          type: "radio-group",
          value: "theme",
          label: "Theme",
          items: [
            { type: "radio", label: "Light", value: "light" },
            { type: "radio", label: "Dark", value: "dark" },
          ],
        },
      ]}
    />
  );
}

Button with Dropdown Menu

import { Dropdown } from "../components/ui";

export default function Page() {
  return (
    <Dropdown.Button
      type="primary"
      items={[{ type: "item", label: "Submit & Close", value: "close" }]}
      onClick={() => console.log("Primary click!")}
    >
      Submit Action
    </Dropdown.Button>
  );
}

Custom styling & semantic classNames

<Dropdown
  trigger={<Button>Styled Dropdown</Button>}
  classNames={{
    content: "custom-menu-card",
    item: "custom-menu-item"
  }}
  styles={{
    content: { boxShadow: "0 4px 20px rgba(0,0,0,0.15)" }
  }}
  items={[{ type: "item", label: "Custom Styled Item", value: "styled" }]}
/>

Center-pointing Arrow

<Dropdown
  trigger={<Button>Center Arrow</Button>}
  arrow={{ pointAtCenter: true }}
  placement="bottomRight"
  items={[{ type: "item", label: "Item 1", value: "1" }]}
/>

Groups and cascading submenus

<Dropdown
  trigger={<Button>Open Dropdown</Button>}
  items={[
    {
      type: "group",
      label: "File",
      items: [
        { type: "item", label: "New", value: "new" },
        { type: "item", label: "Open", value: "open" },
      ],
    },
    { type: "separator" },
    {
      type: "submenu",
      label: "Share",
      items: [
        { type: "item", label: "Email", value: "email" },
        { type: "item", label: "Link", value: "link" },
      ],
    },
  ]}
/>

Custom placement, arrow, and hover trigger

<Dropdown
  trigger={<Button>Hover Me</Button>}
  placement="bottomRight"
  triggerMode="hover"
  arrow={true}
  mouseEnterDelay={100}
  mouseLeaveDelay={150}
  items={[
    { type: "item", label: "Profile", value: "profile" },
    { type: "item", label: "Settings", value: "settings" },
    { type: "separator" },
    { type: "item", label: "Logout", value: "logout" },
  ]}
/>

Context menu

A trigger wired for "contextMenu" opens on right-click, anchored at the pointer, instead of behaving like a button:

<Dropdown
  trigger={<div>Right-click this area</div>}
  trigger={"contextMenu"}
  items={[
    { type: "item", label: "Copy", value: "copy" },
    { type: "item", label: "Paste", value: "paste" },
  ]}
/>

Controlled open state

const [open, setOpen] = useState(false);

<Dropdown
  open={open}
  onOpenChange={setOpen}
  trigger={<Button>Open Dropdown</Button>}
  items={[{ type: "item", label: "Edit", value: "edit" }]}
/>;

CMS Page Builder

This component is available as a menu block in the Page Builder (content/pages/*.json) — the CMS block is labelled "Menu" but renders through this Dropdown component:

{
  "type": "menu",
  "triggerText": "Open Dropdown",
  "items": [
    { "type": "item", "label": "Edit", "value": "edit" },
    { "type": "separator" },
    { "type": "item", "label": "Delete", "value": "delete" }
  ]
}

Props

Dropdown

Prop	Type	Description	Default
`trigger`	`JSX.Element`	Element that opens the menu when activated.	-
`items`	`DropdownItem[]`	The menu items to render.	-
`open`	`boolean`	Whether the menu is open (controlled).	-
`defaultOpen`	`boolean`	Whether the menu is open by default (uncontrolled).	`false`
`disabled`	`boolean`	Disables every trigger mode and renders the trigger inert.	`false`
`interactive`	`boolean`	Forces hydration as an island. Defaults to `true`.	`true`

| arrow | `boolean \ | { pointAtCenter?: boolean }` | Show a pointer arrow pointing from the menu to the trigger. Can align exactly with the trigger's center. | false |

| onOpenChange | `(open: boolean, info?: { source: 'trigger' \ | 'menu' }) => void` | Called when the menu opens or closes. source specifies what triggered the action. | - |

| size | `"xs" \ | "sm" \ | "md" \ | "lg" \ | "xl"` | The size of the menu. | "md" |

classNames and styles slots:

root (or positioner): The overlay absolute positioning container.
content: The popup card containing list items.
item: Individual list item (including checkbox and radio items).
trigger: The main trigger button/wrapper.
arrow: The outer arrow wrapper.
arrowTip: The styled inner diamond.

DropdownItem

Property	Type	Description

Dropdown.Button (DropdownButton)

A Button with a dropdown menu, rendered as a continuous attached button group.

Prop	Type	Description	Default

Supports all common Dropdown props such as items, placement, arrow, classNames, styles, etc.

Note

Please ensure that trigger accepts onMouseEnter, onMouseLeave, onFocus, and onClick — the trigger element is cloned in place with these (and the relevant ARIA/data-*) attributes attached, rather than wrapped.

Limitations

The interactive island positions the menu relative to its trigger's own wrapper (position: absolute, not a portal): it flips to the opposite side when the requested placement would overflow the viewport, and clamps the cross axis so the menu never renders off-screen. It does not track scroll containers or resize observers the way Floating UI does — repositioning only re-runs on window resize while open, and scrolling the page moves the menu along with the trigger for free. A menu opened from deep inside a scrolling or overflow: hidden container can still be visually clipped by that container, the same tradeoff Popover and Tooltip make.

Context menus and submenus are the exception: since they aren't anchored to a trigger's box (a context menu opens at the pointer; a submenu opens beside a menu item), they're positioned with position: fixed and hand-rolled coordinates instead, and are re-run on Escape/scroll/resize like the rest of the menu.

Each submenu is its own nested interactive island, scoped via a data-overlay-root marker so a parent menu's positioning and outside-click logic don't reach into a submenu's own content (and vice versa). Selecting a regular item closes every open menu level it bubbles through; toggling a checkbox/radio item inside any level keeps the whole stack open.

The _closed exit animation (slide-fade-out) plays before the menu is actually removed from layout — closing doesn't hide it instantly.