ButtonDropdown
Button that opens a dropdown menu on click, powered by the ContextMenu overlay system.
import { ButtonDropdown } from "phoundry-ui";Basic
Loading interactive example…
View source
<script lang="ts"> import { ButtonDropdown } from "phoundry-ui"; import type { MenuItem } from "phoundry-ui";
const fileItems: MenuItem[] = [ { id: "new", type: "action", label: "New File", action: () => {} }, { id: "open", type: "action", label: "Open...", action: () => {} }, { type: "separator" }, { id: "save", type: "action", label: "Save", action: () => {} }, { id: "save-as", type: "action", label: "Save As...", action: () => {} }, ];</script>
<ButtonDropdown items={fileItems}>File</ButtonDropdown>Variants
Loading interactive example…
View source
<script lang="ts"> import { ButtonDropdown } from "phoundry-ui"; import type { MenuItem } from "phoundry-ui";
const fileItems: MenuItem[] = [ { id: "new", type: "action", label: "New File", action: () => {} }, { id: "open", type: "action", label: "Open...", action: () => {} }, { type: "separator" }, { id: "save", type: "action", label: "Save", action: () => {} }, { id: "save-as", type: "action", label: "Save As...", action: () => {} }, ];
const dangerItems: MenuItem[] = [ { id: "archive", type: "action", label: "Archive", action: () => {} }, { id: "delete", type: "action", label: "Delete", action: () => {}, danger: true, }, ];</script>
<div class="flex items-center gap-2"> <ButtonDropdown variant="primary" items={fileItems}>Primary</ButtonDropdown> <ButtonDropdown variant="outline" items={fileItems}>Outline</ButtonDropdown> <ButtonDropdown variant="danger" items={dangerItems}>Danger</ButtonDropdown></div>Sizes
Loading interactive example…
View source
<script lang="ts"> import { ButtonDropdown } from "phoundry-ui"; import type { MenuItem } from "phoundry-ui";
const fileItems: MenuItem[] = [ { id: "new", type: "action", label: "New File", action: () => {} }, { id: "open", type: "action", label: "Open...", action: () => {} }, { type: "separator" }, { id: "save", type: "action", label: "Save", action: () => {} }, { id: "save-as", type: "action", label: "Save As...", action: () => {} }, ];</script>
<div class="flex items-center gap-2"> <ButtonDropdown size="xs" items={fileItems}>Extra Small</ButtonDropdown> <ButtonDropdown size="sm" items={fileItems}>Small</ButtonDropdown> <ButtonDropdown size="md" items={fileItems}>Medium</ButtonDropdown> <ButtonDropdown size="lg" items={fileItems}>Large</ButtonDropdown></div>Split: sizes (singleClickAction)
Loading interactive example…
View source
<script lang="ts"> import { ButtonDropdown } from "phoundry-ui"; import type { MenuItem } from "phoundry-ui";
const fileItems: MenuItem[] = [ { id: "new", type: "action", label: "New File", action: () => {} }, { id: "open", type: "action", label: "Open...", action: () => {} }, { type: "separator" }, { id: "save", type: "action", label: "Save", action: () => {} }, { id: "save-as", type: "action", label: "Save As...", action: () => {} }, ];</script>
<div class="flex flex-wrap items-center gap-2"> <ButtonDropdown size="xs" variant="secondary" items={fileItems} singleClickAction={() => {}}>Extra small</ButtonDropdown > <ButtonDropdown size="sm" variant="secondary" items={fileItems} singleClickAction={() => {}}>Small</ButtonDropdown > <ButtonDropdown size="md" variant="secondary" items={fileItems} singleClickAction={() => {}}>Medium</ButtonDropdown > <ButtonDropdown size="lg" variant="secondary" items={fileItems} singleClickAction={() => {}}>Large</ButtonDropdown ></div>Split: variants (singleClickAction)
Loading interactive example…
View source
<script lang="ts"> import { ButtonDropdown } from "phoundry-ui"; import type { MenuItem } from "phoundry-ui";
const fileItems: MenuItem[] = [ { id: "new", type: "action", label: "New File", action: () => {} }, { id: "open", type: "action", label: "Open...", action: () => {} }, { type: "separator" }, { id: "save", type: "action", label: "Save", action: () => {} }, { id: "save-as", type: "action", label: "Save As...", action: () => {} }, ];
const dangerItems: MenuItem[] = [ { id: "archive", type: "action", label: "Archive", action: () => {} }, { id: "delete", type: "action", label: "Delete", action: () => {}, danger: true, }, ];</script>
<div class="flex flex-wrap items-center gap-2"> <ButtonDropdown variant="primary" items={fileItems} singleClickAction={() => {}}>Primary</ButtonDropdown > <ButtonDropdown variant="secondary" items={fileItems} singleClickAction={() => {}}>Secondary</ButtonDropdown > <ButtonDropdown variant="outline" items={fileItems} singleClickAction={() => {}}>Outline</ButtonDropdown > <ButtonDropdown variant="danger" items={dangerItems} singleClickAction={() => {}}>Archive</ButtonDropdown ></div>Split: with icon (singleClickAction)
Loading interactive example…
View source
<script lang="ts"> import { ButtonDropdown } from "phoundry-ui"; import { PhiIcons } from "phoundry-ui"; import type { MenuItem } from "phoundry-ui";
const fileItems: MenuItem[] = [ { id: "new", type: "action", label: "New File", action: () => {} }, { id: "open", type: "action", label: "Open...", action: () => {} }, { type: "separator" }, { id: "save", type: "action", label: "Save", action: () => {} }, { id: "save-as", type: "action", label: "Save As...", action: () => {} }, ];</script>
<div class="flex flex-wrap items-center gap-2"> <ButtonDropdown icon={PhiIcons.edit} variant="primary" items={fileItems} singleClickAction={() => {}}>Save</ButtonDropdown > <ButtonDropdown icon={PhiIcons.edit} size="sm" variant="ghost" items={fileItems} singleClickAction={() => {}}>Save</ButtonDropdown > <ButtonDropdown icon={PhiIcons.launch} items={fileItems} singleClickAction={() => {}}>Export</ButtonDropdown ></div>Without Arrow
Loading interactive example…
View source
<script lang="ts"> import { ButtonDropdown } from "phoundry-ui"; import type { MenuItem } from "phoundry-ui";
const fileItems: MenuItem[] = [ { id: "new", type: "action", label: "New File", action: () => {} }, { id: "open", type: "action", label: "Open...", action: () => {} }, { type: "separator" }, { id: "save", type: "action", label: "Save", action: () => {} }, { id: "save-as", type: "action", label: "Save As...", action: () => {} }, ];</script>
<div class="flex items-center gap-2"> <ButtonDropdown items={fileItems} showArrow={false}>No Arrow</ButtonDropdown> <ButtonDropdown items={fileItems} showArrow={true}>With Arrow</ButtonDropdown></div>Searchable menus
Set searchable to show a search input in each menu level (default: false). Filtering matches labels using a case-insensitive, trimmed substring; spaces inside the query are preserved. Each submenu searches only its own level, and each opening starts fresh. Empty results show “No results found”. Arrow Up/Down move through enabled results, Enter activates a result, and Escape returns from a submenu or closes the root menu.
<ButtonDropdown {items} searchable>Choose action</ButtonDropdown>Placement
Loading interactive example…
View source
<script lang="ts"> import { ButtonDropdown } from "phoundry-ui"; import type { MenuItem } from "phoundry-ui";
const fileItems: MenuItem[] = [ { id: "new", type: "action", label: "New File", action: () => {} }, { id: "open", type: "action", label: "Open...", action: () => {} }, { type: "separator" }, { id: "save", type: "action", label: "Save", action: () => {} }, { id: "save-as", type: "action", label: "Save As...", action: () => {} }, ];</script>
<div class="flex items-center gap-2"> <ButtonDropdown items={fileItems} placement="bottom-start" >Bottom Start</ButtonDropdown > <ButtonDropdown items={fileItems} placement="bottom-end" >Bottom End</ButtonDropdown > <ButtonDropdown items={fileItems} placement="top-start" >Top Start</ButtonDropdown > <ButtonDropdown items={fileItems} placement="top-end">Top End</ButtonDropdown></div>Loading, disabled, tooltip
Loading interactive example…
View source
<script lang="ts"> import { ButtonDropdown } from "phoundry-ui"; import { PhiIcons } from "phoundry-ui"; import type { MenuItem } from "phoundry-ui";
const fileItems: MenuItem[] = [ { id: "new", type: "action", label: "New File", action: () => {} }, { id: "open", type: "action", label: "Open...", action: () => {} }, { type: "separator" }, { id: "save", type: "action", label: "Save", action: () => {} }, { id: "save-as", type: "action", label: "Save As...", action: () => {} }, ];</script>
<p class="mb-2 text-xs text-txt-secondary"> <code>loading</code> shows the same spinner as <code>Button</code> and blocks opening the menu. Icon-only triggers still need <code>title</code> for accessibility.</p><div class="flex flex-wrap gap-2"> <ButtonDropdown items={fileItems} loading>Saving…</ButtonDropdown> <ButtonDropdown items={fileItems} disabled>Unavailable</ButtonDropdown> <ButtonDropdown items={fileItems} icon={PhiIcons.expand} iconOnly title="More actions" variant="ghost" /></div>API
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
itemsrequired | MenuItem[] | (() => MenuItem[]) | — | Menu items to display. Can be a static array or a function that returns items lazily. |
placement | PopoverPlacement | 'bottom-end' | Where the dropdown opens relative to the button (top…right-end; see popover placement types). |
showArrow | boolean | true | Show the chevron indicator. When singleClickAction is set, the chevron is always shown (this prop is effectively ignored in split mode). |
searchable | boolean | false | Show an independent label filter in every menu level. Defaults to false; queries reset on opening. |
singleClickAction | (e: MouseEvent) => void | — | Split control: the main label area runs this handler; the chevron segment opens the menu. Renders as two <button>s; href is ignored. element bind targets the left button. |
iconOnly | boolean | false | Hide label content and use an icon-only trigger. Icon-only layout is also inferred when an icon or loading spinner is present without children. With showArrow=false the trigger is square; split mode keeps a square primary segment. |
…buttonProps: Same fields as Button (variant, size, icon, loading, disabled, active, title, noTooltip, class, element bind, etc.). href / link mode is not supported - use Button + separate menu if you need a link trigger.
Usage tips
- Pass
itemsas a function for lazy evaluation - useful when menu items depend on current state. - Set
placement="bottom"to center the menu beneath the button. Unsuffixed placements center on the corresponding edge;-startand-endalign to its ends. Menus stay within the viewport. - The dropdown uses the same
ContextMenuoverlay, so it requiresprovideContextMenu()(orsetupOverlays()) in a parent layout. - Set
showArrow={false}to hide the chevron for a cleaner look (not used whensingleClickActionis set). - All six variants match
Button:primaryuses the dim accent surface,secondaryuses the base surface,outlineadds a border,dangeruses danger colors, andghostandlinkuse transparent surfaces. Hover and active colors follow the same variant tokens. An open menu holds its trigger in the active style. - The
xs,sm,md, andlgsizes use the shared CSS control-height and icon-size tokens, matchingButton.fullWidthstretches the whole control, including the shell in split mode. - In split mode, the chevron segment’s width equals the whole control’s outer height, including for the outline variant. The segment keeps that width when space is constrained.
- Clicks have no wave animation. Loading spins the icon, and opening rotates the chevron; both respect reduced-motion preferences.
Styling hooks
The stable root selector is .ph-btn-dropdown. Consumer class and style values apply to this root: the button in single mode and the outer shell in split mode. Native attributes, tooltip attachment, and the element binding still target the primary button. Part selectors are internal.
The root exposes data-variant and data-size. Visual customization uses --ph-btn-radius, --ph-comp-h-xs / sm / md / lg, and --ph-comp-icon-xs / sm / md / lg from the shared component stylesheet. The same optional --ph-button-shadow, --ph-button-specular, --ph-button-shading, and --ph-text-shadow overrides used by Button apply here.
Optional motion overrides are --ph-motion-fast (100ms for surface and chevron transitions), --ph-motion-ease-out (ease-out), and --ph-motion-spin (1000ms per loading rotation). Reduced-motion preferences disable these transitions and the spinner animation.