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

<ComponentSection>
  <ComponentExample
    code={`<DropdownMenu>
  <DropdownMenu.Trigger render={<Button icon={PlusIcon}>Add</Button>} />
  <DropdownMenu.Content>
    <DropdownMenu.Item>Worker</DropdownMenu.Item>
    <DropdownMenu.Item>Pages</DropdownMenu.Item>
    <DropdownMenu.Item>KV Namespace</DropdownMenu.Item>
  </DropdownMenu.Content>
</DropdownMenu>`}
  >
    <DropdownBasicDemo client:load />
  </ComponentExample>
</ComponentSection>

<ComponentSection>
  <Heading level={2}>Installation</Heading>
  <Heading level={3}>Barrel</Heading>
  <CodeBlock
    code={`import { DropdownMenu } from "@cloudflare/kumo";`}
    lang="tsx"
  />
  <Heading level={3}>Granular</Heading>
  <CodeBlock
    code={`import { DropdownMenu } from "@cloudflare/kumo/components/dropdown";`}
    lang="tsx"
  />
</ComponentSection>

<ComponentSection>
  <Heading level={2}>Usage</Heading>
  <CodeBlock code={`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>
  );
}`} lang="tsx" />
</ComponentSection>

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

<Heading level={3}>Basic Dropdown</Heading>
<ComponentExample
  code={`<DropdownMenu>
  <DropdownMenu.Trigger render={<Button icon={PlusIcon}>Add</Button>} />
  <DropdownMenu.Content>
    <DropdownMenu.Item>Worker</DropdownMenu.Item>
    <DropdownMenu.Item>Pages</DropdownMenu.Item>
  </DropdownMenu.Content>
</DropdownMenu>`}
>
  <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 code={`<DropdownMenu>

  <DropdownMenu.Trigger render={<Button>View Options</Button>} />
  <DropdownMenu.Content>
    <DropdownMenu.Group>
      <DropdownMenu.Label>Display</DropdownMenu.Label>
      <DropdownMenu.CheckboxItem
        checked={showSidebar}
        onCheckedChange={setShowSidebar}
      >
        Show sidebar
      </DropdownMenu.CheckboxItem>
      <DropdownMenu.CheckboxItem
        checked={showLineNumbers}
        onCheckedChange={setShowLineNumbers}
      >
        Show line numbers
      </DropdownMenu.CheckboxItem>
    </DropdownMenu.Group>
  </DropdownMenu.Content>
</DropdownMenu>`}>
    <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 code={`<DropdownMenu>

  <DropdownMenu.Trigger render={<Button icon={UserIcon}>Account</Button>} />
  <DropdownMenu.Content>
    <DropdownMenu.Item icon={UserIcon}>Profile</DropdownMenu.Item>
    <DropdownMenu.Item icon={CreditCardIcon}>Billing</DropdownMenu.Item>
    <DropdownMenu.Item icon={MoonIcon}>Dark mode</DropdownMenu.Item>

    {/* Language submenu with RadioGroup */}
    <DropdownMenu.Sub>
      <DropdownMenu.SubTrigger>Language</DropdownMenu.SubTrigger>
      <DropdownMenu.SubContent>
        <DropdownMenu.Group>
          <DropdownMenu.RadioGroup value="en">
            <DropdownMenu.RadioItem value="en">
              English
              <DropdownMenu.RadioItemIndicator />
            </DropdownMenu.RadioItem>
            <DropdownMenu.RadioItem value="es">
              Español
              <DropdownMenu.RadioItemIndicator />
            </DropdownMenu.RadioItem>
            {/* ... more languages */}
          </DropdownMenu.RadioGroup>
        </DropdownMenu.Group>
      </DropdownMenu.SubContent>
    </DropdownMenu.Sub>

    {/* Timezone submenu with RadioGroup */}
    <DropdownMenu.Sub>
      <DropdownMenu.SubTrigger>Set Timezone</DropdownMenu.SubTrigger>
      <DropdownMenu.SubContent>
        <DropdownMenu.Group>
          <DropdownMenu.RadioGroup value="America/Los_Angeles">
            <DropdownMenu.RadioItem value="America/Los_Angeles">
              Pacific Time (PT)
              <DropdownMenu.RadioItemIndicator />
            </DropdownMenu.RadioItem>
            <DropdownMenu.RadioItem value="America/New_York">
              Eastern Time (ET)
              <DropdownMenu.RadioItemIndicator />
            </DropdownMenu.RadioItem>
            {/* ... more timezones */}
          </DropdownMenu.RadioGroup>
        </DropdownMenu.Group>
      </DropdownMenu.SubContent>
    </DropdownMenu.Sub>

    <DropdownMenu.Separator />
    <DropdownMenu.Item icon={SignOutIcon} variant="danger">
      Log out
    </DropdownMenu.Item>

  </DropdownMenu.Content>
</DropdownMenu>`}>
    <DropdownNestedDemo 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 code={`<DropdownMenu>

  <DropdownMenu.Trigger render={<Button>Resources</Button>} />
  <DropdownMenu.Content>
    <DropdownMenu.LinkItem href="/settings" icon={GearIcon}>
      Settings
    </DropdownMenu.LinkItem>
    <DropdownMenu.LinkItem href="/docs" icon={BookOpenIcon}>
      Documentation
    </DropdownMenu.LinkItem>
    <DropdownMenu.Separator />
    <DropdownMenu.LinkItem
      href="https://developers.cloudflare.com"
      target="_blank"
      icon={ArrowSquareOutIcon}
    >
      Developer Docs
    </DropdownMenu.LinkItem>
  </DropdownMenu.Content>
</DropdownMenu>`}>
    <DropdownLinkItemDemo client:load />
  </ComponentExample>
</ComponentSection>

<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>
