# Dropdown

Dropdown,
DropdownContent,
DropdownItem,
DropdownLabel,
DropdownSeparator,
DropdownShortcut,
DropdownSub,
DropdownSubContent,
DropdownSubTrigger,
DropdownTrigger,
} from "@/components/starwind/dropdown";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
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>
```
  </div>
  <div slot="react">
```tsx
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>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Runtime dropdown items model menu actions. Use Navigation Menu for site links instead of rendering anchors through `DropdownItem`.

## Installation

```bash
npx starwind@latest add dropdown
```

## Usage

### Action Menu

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

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

> **Info:** The old anchor-polymorphism example is now an action menu because Runtime dropdown items expose menu-item behavior rather than a styled anchor API.

### Hover Open

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

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

> **Info:** Hover opening is handled by the Runtime menu controller; its items remain menu actions and no longer use the legacy `as="a"` API.

### Submenu

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

```astro
---
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>
        <DropdownSeparator />
        <DropdownItem>Calendly</DropdownItem>
        <DropdownItem>Slack</DropdownItem>
        <DropdownItem>Webhook</DropdownItem>
      </DropdownSubContent>
    </DropdownSub>
    <DropdownItem>
      <span>New Team</span>
      <DropdownShortcut>⌘+T</DropdownShortcut>
    </DropdownItem>
  </DropdownContent>
</Dropdown>
```

### Shortcuts

Add `DropdownShortcut` to display keyboard hints alongside actions.

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

### Placement Options

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

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

### With Icons

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

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

## Framework Availability
Dropdown is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## API Reference
### Dropdown
- Inherits div attributes.

### DropdownTrigger
- Inherits button attributes.

### DropdownContent
- Inherits div attributes.

### DropdownItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
- Inherits div attributes.

### DropdownCheckboxItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `closeOnClick` | `boolean` | No | `false` | Wrapper prop | Closes the containing surface after the item is activated. |
| `indicatorClass` | `string` | No | - | Wrapper prop | Adds classes to the generated selection indicator. |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
| `showIndicator` | `boolean` | No | `true` | Wrapper prop | Shows the generated selection indicator. |
- Inherits div attributes. Omits `aria-checked` and `role`.

### DropdownCheckboxItemIndicator
- Inherits span attributes.

### DropdownRadioGroup
- Inherits div attributes.

### DropdownRadioItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `closeOnClick` | `boolean` | No | `false` | Wrapper prop | Closes the containing surface after the item is activated. |
| `indicatorClass` | `string` | No | - | Wrapper prop | Adds classes to the generated selection indicator. |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
| `showIndicator` | `boolean` | No | `true` | Wrapper prop | Shows the generated selection indicator. |
| `value` | `string` | Yes | - | Wrapper prop | Controls or identifies the component value. |
- Inherits div attributes. Omits `aria-checked` and `role`.

### DropdownRadioItemIndicator
- Inherits span attributes.

### DropdownGroup
- Inherits div attributes.

### DropdownLabel
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
- Inherits div attributes.

### DropdownSeparator
- Inherits div attributes.

### DropdownShortcut
- Inherits span attributes.

### DropdownSub
- Inherits div attributes.

### DropdownSubTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `inset` | `boolean` | No | `false` | Wrapper prop | Adds leading inset spacing for visual alignment. |
- Inherits div attributes.

### DropdownSubContent
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | No | `"right"` | Primitive override | Selects the preferred side for floating content. |
| `sideOffset` | `number` | No | `0` | Primitive override | Sets the distance in pixels between floating content and its anchor. |
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Menu Primitive](/docs/primitives/menu/)
- Runtime factory: [`createMenu`](/docs/runtime/#create-menu) from `@starwind-ui/runtime/menu`

## Changelog

### v3.0.0

- Rebuilt Dropdown on Starwind Runtime while preserving its styled API over the shared Menu behavior.
- See the [Menu Primitive](/docs/primitives/menu/) for the underlying unstyled anatomy and behavior API.