---
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 Heading from "~/components/docs/Heading.astro";
import PropsTable from "~/components/docs/PropsTable.astro";
import {
  DropdownBasicDemo,
  DropdownCheckboxDemo,
  DropdownNestedDemo,
  DropdownAvatarTriggerDemo,
  DropdownLinkItemDemo,
} from "~/components/demos/DropdownDemo";

{/* Hero Demo */}

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

{/* Installation */}

<ComponentSection>
  <Heading level={2}>Installation</Heading>
  <Heading level={3}>Barrel</Heading>

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

<Heading level={3}>Granular</Heading>

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

</ComponentSection>

{/* Usage */}

<ComponentSection>
  <Heading level={2}>Usage</Heading>

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

export default function Example() {
  return (
    <DropdownMenu>
      <DropdownMenu.Trigger render={<Button>Menu</Button>} />
      <DropdownMenu.Content>
        <DropdownMenu.Item>Option 1</DropdownMenu.Item>
        <DropdownMenu.Item>Option 2</DropdownMenu.Item>
      </DropdownMenu.Content>
    </DropdownMenu>
  );
}
```

</ComponentSection>

{/* Examples */}

<ComponentSection>
  <Heading level={2}>Examples</Heading>

<Heading level={3}>Basic Dropdown</Heading>
<ComponentExample demo="DropdownBasicDemo">
  <DropdownBasicDemo client:load />
</ComponentExample>

<Heading level={3}>Checkbox Items</Heading>
<p>
  Use `DropdownMenu.CheckboxItem` for toggleable options that can be
  independently checked or unchecked.
</p>
<ComponentExample demo="DropdownCheckboxDemo">
  <DropdownCheckboxDemo client:load />
</ComponentExample>

<Heading level={3}>Nested Menu with Radio Selection</Heading>
<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>

<Heading level={3}>Custom Trigger with Avatar</Heading>
<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>

<Heading level={3}>Navigation Links</Heading>
<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>
  <Heading level={2}>API Reference</Heading>

<Heading level={3}>DropdownMenu</Heading>
<p>Root component that manages the dropdown state.</p>
<PropsTable component="DropdownMenu" />

<Heading level={3}>DropdownMenu.Trigger</Heading>
<p>Button that opens the dropdown when clicked.</p>
<PropsTable component="DropdownMenu.Trigger" />

<Heading level={3}>DropdownMenu.Item</Heading>
<p>Individual menu item for actions.</p>
<PropsTable component="DropdownMenu.Item" />

<Heading level={3}>DropdownMenu.LinkItem</Heading>
<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" />

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

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

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

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

<Heading level={3}>DropdownMenu.Separator</Heading>
<p>A visual divider between menu items.</p>
<PropsTable component="DropdownMenu.Separator" />

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

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

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

</ComponentSection>
