---
layout: ~/layouts/MdxDocLayout.astro
title: "Dropdown Menu"
description: "Displays a menu to the user—such as a set of actions or functions—triggered by a button."
sourceFile: "components/dropdown"
baseUIComponent: "menu"
---

import ComponentExample from "~/components/docs/ComponentExample.astro";
import ComponentSection from "~/components/docs/ComponentSection.astro";
import PropsTable from "~/components/docs/PropsTable.astro";
import {
  DropdownBasicDemo,
  DropdownInsetDemo,
  DropdownOnClickDemo,
  DropdownCheckboxDemo,
  DropdownNestedDemo,
  DropdownAvatarTriggerDemo,
  DropdownLinkItemDemo,
} from "~/components/demos/DropdownDemo";

{/* Hero Demo */}

<ComponentSection>
  <ComponentExample demo="DropdownBasicDemo">
    <DropdownBasicDemo client:load />
  </ComponentExample>
</ComponentSection>

{/* Installation */}

<ComponentSection>

## Installation

### Barrel

```tsx
import { DropdownMenu } from "@cloudflare/kumo";
```

### Granular

```tsx
import { DropdownMenu } from "@cloudflare/kumo/components/dropdown";
```

</ComponentSection>

{/* Usage */}

<ComponentSection>

## Usage

```tsx
import { DropdownMenu, Button } from "@cloudflare/kumo";

export default function Example() {
  return (
    <DropdownMenu>
      <DropdownMenu.Trigger render={<Button>Menu</Button>} />
      <DropdownMenu.Content>
        <DropdownMenu.Item onClick={() => console.log("edit")}>
          Edit
        </DropdownMenu.Item>
        <DropdownMenu.Item onClick={() => console.log("duplicate")}>
          Duplicate
        </DropdownMenu.Item>
        <DropdownMenu.Separator />
        <DropdownMenu.Item
          variant="danger"
          onClick={() => console.log("delete")}
        >
          Delete
        </DropdownMenu.Item>
      </DropdownMenu.Content>
    </DropdownMenu>
  );
}
```

</ComponentSection>

{/* Examples */}

<ComponentSection>

## Examples

### Basic Dropdown

<ComponentExample demo="DropdownBasicDemo">
  <DropdownBasicDemo client:load />
</ComponentExample>

### Inset Items

<p>
  Use `inset` on items without an icon to align their text with items that have one.
</p>
<ComponentExample demo="DropdownInsetDemo">
  <DropdownInsetDemo client:load />
</ComponentExample>

### Handling Item Clicks

<p>
  Use `onClick` on `DropdownMenu.Item` to handle actions. Each item receives a standard React mouse event handler.
</p>
<ComponentExample demo="DropdownOnClickDemo">
  <DropdownOnClickDemo client:load />
</ComponentExample>

### Checkbox Items

<p>
  Use `DropdownMenu.CheckboxItem` for toggleable options that can be
  independently checked or unchecked.
</p>
<ComponentExample demo="DropdownCheckboxDemo">
  <DropdownCheckboxDemo client:load />
</ComponentExample>

### Nested Menu with Radio Selection

<p>
  Use `DropdownMenu.Sub`, `DropdownMenu.SubTrigger`, and
  `DropdownMenu.SubContent` to create nested submenus. For single-selection
  lists like language or timezone, use `DropdownMenu.RadioGroup` and
  `DropdownMenu.RadioItem`.
</p>
<ComponentExample demo="DropdownNestedDemo">
  <DropdownNestedDemo client:load />
</ComponentExample>

### Custom Trigger with Avatar

<p>
  Use the `render` prop to customize the trigger element while passing children
  to render inside it. This is useful when you need a non-button trigger (like
  an avatar) wrapped in an accessible button element.
</p>
<ComponentExample demo="DropdownAvatarTriggerDemo">
  <DropdownAvatarTriggerDemo client:load />
</ComponentExample>

### Navigation Links

<p>
  Use `DropdownMenu.LinkItem` for menu items that navigate to a URL.
  This renders a semantic `<a>` element with full control over link attributes like `target` and `rel`.
</p>
<ComponentExample demo="DropdownLinkItemDemo">
  <DropdownLinkItemDemo client:load />
</ComponentExample>

</ComponentSection>

{/* API Reference */}

<ComponentSection>

## API Reference

### DropdownMenu

<p>Root component that manages the dropdown state.</p>
<PropsTable component="DropdownMenu" />

### DropdownMenu.Trigger

<p>Button that opens the dropdown when clicked.</p>
<PropsTable component="DropdownMenu.Trigger" />

### DropdownMenu.Item

<p>Individual menu item for actions.</p>
<PropsTable component="DropdownMenu.Item" />

### DropdownMenu.LinkItem

<p>
  A menu item that navigates to a URL. Renders a semantic `<a>` element. Use this instead of `Item` for navigation links.
</p>
<PropsTable component="DropdownMenu.LinkItem" />

### DropdownMenu.CheckboxItem

<p>
  A menu item that can be toggled on or off. Use for independent boolean
  options.
</p>
<PropsTable component="DropdownMenu.CheckboxItem" />

### DropdownMenu.Sub

<p>
  Root component for a nested submenu. Wrap SubTrigger and SubContent inside
  this.
</p>
<PropsTable component="DropdownMenu.Sub" />

### DropdownMenu.SubTrigger

<p>
  Menu item that opens a nested submenu when hovered or clicked. Displays a
  caret icon automatically.
</p>
<PropsTable component="DropdownMenu.SubTrigger" />

### DropdownMenu.SubContent

<p>Container for submenu items. Positioned relative to the SubTrigger.</p>
<PropsTable component="DropdownMenu.SubContent" />

### DropdownMenu.Separator

<p>A visual divider between menu items.</p>
<PropsTable component="DropdownMenu.Separator" />

### DropdownMenu.RadioGroup

<p>
  Groups radio items for single-selection behavior. Only one item can be
  selected at a time.
</p>
<PropsTable component="DropdownMenu.RadioGroup" />

### DropdownMenu.RadioItem

<p>
  A menu item that works like a radio button. Must be used inside a RadioGroup.
</p>
<PropsTable component="DropdownMenu.RadioItem" />

### DropdownMenu.RadioItemIndicator

<p>
  Shows the selected state for a RadioItem. Displays a checkmark by default.
</p>
<PropsTable component="DropdownMenu.RadioItemIndicator" />

</ComponentSection>
