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> );}Runtime example adjustment
Runtime dropdown items model menu actions. Use Navigation Menu for site links instead of rendering anchors through DropdownItem.
Installation
pnpx starwind@latest add dropdownnpx starwind@latest add dropdownyarn dlx starwind@latest add dropdownFramework Availability
Astro Available React AvailableDropdown is available for Astro and React.
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.
---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>Runtime example adjustment
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.
---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>Runtime example adjustment
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.
---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.
---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.
---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.
---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>API Reference
Styled Component API
These props are added or materially changed by the installed Astro styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Follow the Primitive and Runtime links for lower-level behavior props.
Dropdown Item
Inherits div attributes.
Contains the following additional props:
inset boolean false
- Description
- Adds leading inset spacing for visual alignment.
- Classification
- Wrapper prop
Dropdown Checkbox Item
Inherits div attributes. Omits `aria-checked` and `role`.
Contains the following additional props:
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
Dropdown Radio Item
Inherits div attributes. Omits `aria-checked` and `role`.
Contains the following additional props:
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
Dropdown Label
Inherits div attributes.
Contains the following additional props:
inset boolean false
- Description
- Adds leading inset spacing for visual alignment.
- Classification
- Wrapper prop
Dropdown Sub Trigger
Inherits div attributes.
Contains the following additional props:
inset boolean false
- Description
- Adds leading inset spacing for visual alignment.
- Classification
- Wrapper prop
Dropdown Sub Content
Inherits div attributes.
Contains the following additional props:
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
Runtime API
- Menu primitive
createMenufrom@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 for the underlying unstyled anatomy and behavior API.