On this page

Dropdown

---
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownLabel, DropdownSeparator } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button>Open Menu</Button>
  </DropdownTrigger>
  <DropdownContent>
    <DropdownLabel>My Account</DropdownLabel>
    <DropdownSeparator />
    <DropdownItem>Profile</DropdownItem>
    <DropdownItem>Settings</DropdownItem>
    <DropdownSeparator />
    <DropdownItem>Help</DropdownItem>
    <DropdownItem disabled>Sign out</DropdownItem>
  </DropdownContent>
</Dropdown>

import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownLabel, DropdownSeparator } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <Dropdown>
      <DropdownTrigger asChild>
        <Button>Open Menu</Button>
      </DropdownTrigger>
      <DropdownContent>
        <DropdownLabel>My Account</DropdownLabel>
        <DropdownSeparator />
        <DropdownItem>Profile</DropdownItem>
        <DropdownItem>Settings</DropdownItem>
        <DropdownSeparator />
        <DropdownItem>Help</DropdownItem>
        <DropdownItem disabled>Sign out</DropdownItem>
      </DropdownContent>
    </Dropdown>
  );
}

Installation

pnpx starwind@latest add dropdown

npx starwind@latest add dropdown

yarn dlx starwind@latest add dropdown

Usage

A common use case is a compact list of application actions. Each DropdownItem participates in the Runtime menu’s keyboard navigation and selection behavior.

---
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button>Navigation</Button>
  </DropdownTrigger>
  <DropdownContent align="center">
    <DropdownItem>Open dashboard</DropdownItem>
    <DropdownItem>Create project</DropdownItem>
    <DropdownItem>Invite teammate</DropdownItem>
    <DropdownItem>View activity</DropdownItem>
    <DropdownItem>Account settings</DropdownItem>
  </DropdownContent>
</Dropdown>

import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Dropdown>
        <DropdownTrigger asChild>
          <Button>Navigation</Button>
        </DropdownTrigger>
        <DropdownContent align="center">
          <DropdownItem>Open dashboard</DropdownItem>
          <DropdownItem>Create project</DropdownItem>
          <DropdownItem>Invite teammate</DropdownItem>
          <DropdownItem>View activity</DropdownItem>
          <DropdownItem>Account settings</DropdownItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}

Link Items

Use DropdownItem for commands in the current interface and DropdownLinkItem for navigation. Link items render native anchors, accept normal anchor attributes, and participate in the same keyboard navigation and highlighting as action items.

---
import { Dropdown, DropdownTrigger, DropdownContent, DropdownLinkItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button variant="outline">Resources</Button>
  </DropdownTrigger>
  <DropdownContent align="center">
    <DropdownLinkItem href="/docs/">Documentation</DropdownLinkItem>
    <DropdownLinkItem href="/docs/getting-started/">Getting started</DropdownLinkItem>
    <DropdownLinkItem href="/docs/components/dropdown/" disabled>
      Disabled destination
    </DropdownLinkItem>
  </DropdownContent>
</Dropdown>

import { Dropdown, DropdownTrigger, DropdownContent, DropdownLinkItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <Dropdown>
      <DropdownTrigger asChild>
        <Button variant="outline">Resources</Button>
      </DropdownTrigger>
      <DropdownContent align="center">
        <DropdownLinkItem href="/docs/">Documentation</DropdownLinkItem>
        <DropdownLinkItem href="/docs/getting-started/">Getting started</DropdownLinkItem>
        <DropdownLinkItem href="/docs/components/dropdown/" disabled>
          Disabled destination
        </DropdownLinkItem>
      </DropdownContent>
    </Dropdown>
  );
}

Disabled link items omit their href and expose the same disabled state as other menu items. DropdownLinkItem keeps the menu open by default; set closeOnClick when navigation does not unload the current page and the menu should close immediately.

Hover Open

The dropdown can be configured to open on hover in addition to click.

---
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownLabel, DropdownSeparator } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown openOnHover closeDelay={300}>
  <DropdownTrigger asChild>
    <Button>Hover Me</Button>
  </DropdownTrigger>
  <DropdownContent>
    <DropdownLabel>My Account</DropdownLabel>
    <DropdownSeparator />
    <DropdownItem>Profile</DropdownItem>
    <DropdownItem>Settings</DropdownItem>
    <DropdownSeparator />
    <DropdownItem>Help</DropdownItem>
    <DropdownItem disabled>Sign out</DropdownItem>
  </DropdownContent>
</Dropdown>

import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownLabel, DropdownSeparator } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Dropdown openOnHover closeDelay={300}>
        <DropdownTrigger asChild>
          <Button>Hover Me</Button>
        </DropdownTrigger>
        <DropdownContent>
          <DropdownLabel>My Account</DropdownLabel>
          <DropdownSeparator />
          <DropdownItem>Profile</DropdownItem>
          <DropdownItem>Settings</DropdownItem>
          <DropdownSeparator />
          <DropdownItem>Help</DropdownItem>
          <DropdownItem disabled>Sign out</DropdownItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}

Submenu

Use DropdownSub, DropdownSubTrigger, and DropdownSubContent to nest secondary actions.

---
import {
  Dropdown,
  DropdownContent,
  DropdownItem,
  DropdownSeparator,
  DropdownShortcut,
  DropdownSub,
  DropdownSubContent,
  DropdownSubTrigger,
  DropdownTrigger,
} from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button variant="outline">Open</Button>
  </DropdownTrigger>
  <DropdownContent class="min-w-[10rem]">
    <DropdownItem>Team</DropdownItem>
    <DropdownSub>
      <DropdownSubTrigger>Invite users</DropdownSubTrigger>
      <DropdownSubContent>
        <DropdownItem>Email</DropdownItem>
        <DropdownItem>Message</DropdownItem>
        <DropdownSub>
          <DropdownSubTrigger>More options</DropdownSubTrigger>
          <DropdownSubContent>
            <DropdownItem>Calendly</DropdownItem>
            <DropdownItem>Slack</DropdownItem>
            <DropdownSeparator />
            <DropdownItem>Webhook</DropdownItem>
          </DropdownSubContent>
        </DropdownSub>
        <DropdownSeparator />
        <DropdownItem>Advanced...</DropdownItem>
      </DropdownSubContent>
    </DropdownSub>
    <DropdownItem>
      <span>New Team</span>
      <DropdownShortcut>⌘+T</DropdownShortcut>
    </DropdownItem>
  </DropdownContent>
</Dropdown>

import {
  Dropdown,
  DropdownContent,
  DropdownItem,
  DropdownSeparator,
  DropdownShortcut,
  DropdownSub,
  DropdownSubContent,
  DropdownSubTrigger,
  DropdownTrigger,
} from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Dropdown>
        <DropdownTrigger asChild>
          <Button variant="outline">Open</Button>
        </DropdownTrigger>
        <DropdownContent className="min-w-[10rem]">
          <DropdownItem>Team</DropdownItem>
          <DropdownSub>
            <DropdownSubTrigger>Invite users</DropdownSubTrigger>
            <DropdownSubContent>
              <DropdownItem>Email</DropdownItem>
              <DropdownItem>Message</DropdownItem>
              <DropdownSub>
                <DropdownSubTrigger>More options</DropdownSubTrigger>
                <DropdownSubContent>
                  <DropdownItem>Calendly</DropdownItem>
                  <DropdownItem>Slack</DropdownItem>
                  <DropdownSeparator />
                  <DropdownItem>Webhook</DropdownItem>
                </DropdownSubContent>
              </DropdownSub>
              <DropdownSeparator />
              <DropdownItem>Advanced...</DropdownItem>
            </DropdownSubContent>
          </DropdownSub>
          <DropdownItem>
            <span>New Team</span>
            <DropdownShortcut>⌘+T</DropdownShortcut>
          </DropdownItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}

Shortcuts

Add DropdownShortcut to display keyboard hints alongside actions.

---
import {
  Dropdown,
  DropdownContent,
  DropdownItem,
  DropdownLabel,
  DropdownSeparator,
  DropdownShortcut,
  DropdownTrigger,
} from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button variant="outline">Open</Button>
  </DropdownTrigger>
  <DropdownContent>
    <DropdownLabel>My Account</DropdownLabel>
    <DropdownItem>
      <span>Profile</span>
      <DropdownShortcut>⇧⌘P</DropdownShortcut>
    </DropdownItem>
    <DropdownItem>
      <span>Billing</span>
      <DropdownShortcut>⌘B</DropdownShortcut>
    </DropdownItem>
    <DropdownItem>
      <span>Settings</span>
      <DropdownShortcut>⌘S</DropdownShortcut>
    </DropdownItem>
    <DropdownSeparator />
    <DropdownItem>
      <span>Log out</span>
      <DropdownShortcut>⇧⌘Q</DropdownShortcut>
    </DropdownItem>
  </DropdownContent>
</Dropdown>

import {
  Dropdown,
  DropdownContent,
  DropdownItem,
  DropdownLabel,
  DropdownSeparator,
  DropdownShortcut,
  DropdownTrigger,
} from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <Dropdown>
        <DropdownTrigger asChild>
          <Button variant="outline">Open</Button>
        </DropdownTrigger>
        <DropdownContent>
          <DropdownLabel>My Account</DropdownLabel>
          <DropdownItem>
            <span>Profile</span>
            <DropdownShortcut>⇧⌘P</DropdownShortcut>
          </DropdownItem>
          <DropdownItem>
            <span>Billing</span>
            <DropdownShortcut>⌘B</DropdownShortcut>
          </DropdownItem>
          <DropdownItem>
            <span>Settings</span>
            <DropdownShortcut>⌘S</DropdownShortcut>
          </DropdownItem>
          <DropdownSeparator />
          <DropdownItem>
            <span>Log out</span>
            <DropdownShortcut>⇧⌘Q</DropdownShortcut>
          </DropdownItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}

Placement Options

You can position the dropdown menu in different ways by customizing the side and align properties.

---
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
---

<div class="flex gap-4">
  <Dropdown>
    <DropdownTrigger asChild>
      <Button>Left (Start)</Button>
    </DropdownTrigger>
    <DropdownContent align="start">
      <DropdownItem>Option 1</DropdownItem>
      <DropdownItem>Option 2</DropdownItem>
      <DropdownItem>Option 3</DropdownItem>
    </DropdownContent>
  </Dropdown>
  <Dropdown>
    <DropdownTrigger asChild>
      <Button>Center</Button>
    </DropdownTrigger>
    <DropdownContent align="center">
      <DropdownItem>Option 1</DropdownItem>
      <DropdownItem>Option 2</DropdownItem>
      <DropdownItem>Option 3</DropdownItem>
    </DropdownContent>
  </Dropdown>
  <Dropdown>
    <DropdownTrigger asChild>
      <Button>Right (End)</Button>
    </DropdownTrigger>
    <DropdownContent align="end">
      <DropdownItem>Option 1</DropdownItem>
      <DropdownItem>Option 2</DropdownItem>
      <DropdownItem>Option 3</DropdownItem>
    </DropdownContent>
  </Dropdown>
</div>

import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";

export function Example() {
  return (
    <>
      <div className="flex gap-4">
        <Dropdown>
          <DropdownTrigger asChild>
            <Button>Left (Start)</Button>
          </DropdownTrigger>
          <DropdownContent align="start">
            <DropdownItem>Option 1</DropdownItem>
            <DropdownItem>Option 2</DropdownItem>
            <DropdownItem>Option 3</DropdownItem>
          </DropdownContent>
        </Dropdown>
        <Dropdown>
          <DropdownTrigger asChild>
            <Button>Center</Button>
          </DropdownTrigger>
          <DropdownContent align="center">
            <DropdownItem>Option 1</DropdownItem>
            <DropdownItem>Option 2</DropdownItem>
            <DropdownItem>Option 3</DropdownItem>
          </DropdownContent>
        </Dropdown>
        <Dropdown>
          <DropdownTrigger asChild>
            <Button>Right (End)</Button>
          </DropdownTrigger>
          <DropdownContent align="end">
            <DropdownItem>Option 1</DropdownItem>
            <DropdownItem>Option 2</DropdownItem>
            <DropdownItem>Option 3</DropdownItem>
          </DropdownContent>
        </Dropdown>
      </div>
    </>
  );
}

With Icons

You can add icons to dropdown items for better visual cues.

---
import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownLabel, DropdownSeparator } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
import Copy from "@tabler/icons/outline/copy.svg";
import Edit from "@tabler/icons/outline/edit.svg";
---

<Dropdown>
  <DropdownTrigger asChild>
    <Button>Actions</Button>
  </DropdownTrigger>
  <DropdownContent>
    <DropdownLabel>Actions</DropdownLabel>
    <DropdownSeparator />
    <DropdownItem>
      <Copy />
      Copy
    </DropdownItem>
    <DropdownItem>
      <Edit />
      Edit
    </DropdownItem>
    <DropdownSeparator />
    <DropdownLabel>Danger Zone</DropdownLabel>
    <DropdownItem inset>Archive</DropdownItem>
    <DropdownItem inset disabled>Delete</DropdownItem>
  </DropdownContent>
</Dropdown>

import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownLabel, DropdownSeparator } from "@/components/starwind/dropdown";
import { Button } from "@/components/starwind/button";
import { IconCopy as Copy } from "@tabler/icons-react";
import { IconEdit as Edit } from "@tabler/icons-react";

export function Example() {
  return (
    <>
      <Dropdown>
        <DropdownTrigger asChild>
          <Button>Actions</Button>
        </DropdownTrigger>
        <DropdownContent>
          <DropdownLabel>Actions</DropdownLabel>
          <DropdownSeparator />
          <DropdownItem>
            <Copy />
            Copy
          </DropdownItem>
          <DropdownItem>
            <Edit />
            Edit
          </DropdownItem>
          <DropdownSeparator />
          <DropdownLabel>Danger Zone</DropdownLabel>
          <DropdownItem inset>Archive</DropdownItem>
          <DropdownItem inset disabled>Delete</DropdownItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Inherits button attributes.

Contains the following additional props:

Prop Type Default

asChild boolean false

Description: Merges the component behavior and props into its child element.
Classification: Primitive override
Primitive prop: menu.Trigger.asChild

Inherits div attributes.

Contains the following additional props:

Prop Type Default

inset boolean false

Description: Adds leading inset spacing for visual alignment.
Classification: Wrapper prop

Inherits a attributes.

Contains the following additional props:

Prop Type Default

closeOnClick boolean false

Description: Closes the containing surface after the item is activated.
Classification: Wrapper prop

inset boolean false

Description: Adds leading inset spacing for visual alignment.
Classification: Wrapper prop

Inherits div attributes. Omits `aria-checked` and `role`.

Contains the following additional props:

Prop Type Default

closeOnClick boolean false

Description: Closes the containing surface after the item is activated.
Classification: Wrapper prop

indicatorClass string —

Description: Adds classes to the generated selection indicator.
Classification: Wrapper prop

inset boolean false

Description: Adds leading inset spacing for visual alignment.
Classification: Wrapper prop

showIndicator boolean true

Description: Shows the generated selection indicator.
Classification: Wrapper prop

Inherits div attributes. Omits `aria-checked` and `role`.

Contains the following additional props:

Prop Type Default

closeOnClick boolean false

Description: Closes the containing surface after the item is activated.
Classification: Wrapper prop

indicatorClass string —

Description: Adds classes to the generated selection indicator.
Classification: Wrapper prop

inset boolean false

Description: Adds leading inset spacing for visual alignment.
Classification: Wrapper prop

showIndicator boolean true

Description: Shows the generated selection indicator.
Classification: Wrapper prop

value Required string —

Description: Controls or identifies the component value.
Classification: Wrapper prop

Inherits div attributes.

Contains the following additional props:

Prop Type Default

inset boolean false

Description: Adds leading inset spacing for visual alignment.
Classification: Wrapper prop

Inherits div attributes.

Contains the following additional props:

Prop Type Default

inset boolean false

Description: Adds leading inset spacing for visual alignment.
Classification: Wrapper prop

Inherits div attributes.

Contains the following additional props:

Prop Type Default

side "top" | "right" | "bottom" | "left" "right"

Description: Selects the preferred side for floating content.
Classification: Primitive override
Primitive prop: menu.Popup.side

sideOffset number 0

Description: Sets the distance in pixels between floating content and its anchor.
Classification: Primitive override
Primitive prop: menu.Popup.sideOffset

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Dropdown.

Primitive API

Menu Primitive

Runtime API

Menu primitive: createMenu from @starwind-ui/runtime/menu

Changelog

v3.1.1

Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

v3.1.0

Added DropdownLinkItem for native anchor navigation; replace legacy DropdownItem as="a" usage with this dedicated part.

v3.0.0

Rebuilt Dropdown on Starwind Runtime while preserving its styled API over the shared Menu behavior.
See the Menu Primitive for the underlying unstyled anatomy and behavior API.

Dropdown

Installation

Usage

Action Menu

Link Items

Hover Open

Submenu

Shortcuts

Placement Options

With Icons

API Reference

Dropdown Trigger

Dropdown Item

Dropdown Link Item

Dropdown Checkbox Item

Dropdown Radio Item

Dropdown Label

Dropdown Sub Trigger

Dropdown Sub Content

Changelog

v3.1.1

v3.1.0

v3.0.0