DropdownMenu
Menu of actions with checkbox and radio items, as an action sheet on phones.
Example
import { useState } from "react";
import {
Button,
DropdownMenu,
DropdownMenuCheckboxItem,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuLabel,
DropdownMenuSeparator,
DropdownMenuTrigger
} from "@porcelana/ui";
import { EditIcon, CopyIcon } from "@porcelana/icons";
export default function Example() {
const [snooze, setSnooze] = useState(true);
return (
<DropdownMenu>
<DropdownMenuTrigger asChild>
<Button variant="soft">Options</Button>
</DropdownMenuTrigger>
<DropdownMenuContent>
<DropdownMenuLabel>Alarm</DropdownMenuLabel>
<DropdownMenuItem icon={<EditIcon size={18} />} shortcut="⌘E">
Edit
</DropdownMenuItem>
<DropdownMenuItem icon={<CopyIcon size={18} />}>Duplicate</DropdownMenuItem>
<DropdownMenuCheckboxItem checked={snooze} onCheckedChange={setSnooze}>
Snooze enabled
</DropdownMenuCheckboxItem>
<DropdownMenuSeparator />
<DropdownMenuItem danger>Delete</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
);
}Import
import { DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem } from "@porcelana/ui";
import "@porcelana/ui/styles.css"; // once, at your app rootProps
Generated from the TypeScript types. Standard HTML attributes are passed through and not listed.
DropdownMenuContent
| Prop | Type | Default | Description |
|---|---|---|---|
align | "center" | "start" | "end" | – | Alignment against the trigger. |
alignOffset | number | – | Offset from the alignment edge in px. |
aria-label | string | – | Defines a string value that labels the current element. @see aria-labelledby. |
arrowPadding | number | – | Padding between the arrow and the content edges in px. |
asChild | boolean | – | Render the single child element instead, merging props and behaviour onto it. |
avoidCollisions | boolean | – | Flip or shift to stay on screen. |
collisionBoundary | Boundary | Boundary[] | – | Element(s) used as the collision boundary instead of the viewport. |
collisionPadding | number | Partial<Record<"top" | "right" | "bottom" | "left", number>> | 8 | Space to keep from the viewport edges in px. |
forceMount | true | – | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. |
hideWhenDetached | boolean | – | Hide when the trigger scrolls out of view. |
id | string | – | Element id. Generated automatically when omitted. |
loop | boolean | – | Whether keyboard navigation should loop around @defaultValue false |
onCloseAutoFocus | ((event: Event) => void) | – | Event handler called when auto-focusing on close. Can be prevented. |
onEscapeKeyDown | ((event: KeyboardEvent) => void) | – | Called on Escape; call event.preventDefault() to keep it open. |
onFocusOutside | ((event: FocusOutsideEvent) => void) | – | Called when focus moves outside. |
onInteractOutside | ((event: PointerDownOutsideEvent | FocusOutsideEvent) => void) | – | Called on any interaction outside; preventDefault() keeps it open. |
onPointerDownOutside | ((event: PointerDownOutsideEvent) => void) | – | Called on a pointer down outside; preventDefault() keeps it open. |
sheetOnMobile | boolean | true | Render as a bottom action sheet under 640px. Defaults to true. |
side | "top" | "right" | "bottom" | "left" | – | Preferred side of the trigger to render on. |
sideOffset | number | 8 | Distance from the trigger in px. |
sticky | Sticky | – | Keep the content attached while scrolling. |
updatePositionStrategy | UpdatePositionStrategy | – | "optimized" or "always" recompute the position on every frame. |
DropdownMenuItem
| Prop | Type | Default | Description |
|---|---|---|---|
aria-label | string | – | Defines a string value that labels the current element. @see aria-labelledby. |
asChild | boolean | – | Render the single child element instead, merging props and behaviour onto it. |
danger | boolean | – | Style as a destructive action. |
disabled | boolean | – | Prevents interaction and dims the control. |
icon | ReactNode | – | Leading icon (decorative). |
id | string | – | Element id. Generated automatically when omitted. |
onSelect | ((event: Event) => void) | – | Called when the item is chosen; event.preventDefault() keeps the menu open. |
shortcut | string | – | Keyboard hint shown on the right. Visual only. |
textValue | string | – | Text used for typeahead when the item's content isn't plain text. |
DropdownMenuCheckboxItem
| Prop | Type | Default | Description |
|---|---|---|---|
aria-label | string | – | Defines a string value that labels the current element. @see aria-labelledby. |
asChild | boolean | – | Render the single child element instead, merging props and behaviour onto it. |
checked | CheckedState | – | Controlled checked state. Use with onCheckedChange. |
disabled | boolean | – | Prevents interaction and dims the control. |
id | string | – | Element id. Generated automatically when omitted. |
onCheckedChange | ((checked: boolean) => void) | – | Called with the new checked state. |
onSelect | ((event: Event) => void) | – | Called when the item is chosen; event.preventDefault() keeps the menu open. |
textValue | string | – | Text used for typeahead when the item's content isn't plain text. |
Accessibility
- Opens with Enter, Space or ↓; arrows and typeahead move between items.
- Checkbox and radio items announce their state; shortcuts are visual only.
Mobile
- Under 640px it becomes a bottom action sheet with 56px items (turn off with sheetOnMobile={false}).