Skip to content

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
basic.svelte
<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
variants.svelte
<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
sizes.svelte
<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
split-sizes-singleclickaction.svelte
<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
split-variants-singleclickaction.svelte
<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
split-with-icon-singleclickaction.svelte
<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
without-arrow.svelte
<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
placement.svelte
<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
loading-disabled-tooltip.svelte
<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

NameTypeDefaultDescription
itemsrequiredMenuItem[] | (() => MenuItem[])—Menu items to display. Can be a static array or a function that returns items lazily.
placementPopoverPlacement'bottom-end'Where the dropdown opens relative to the button (top…right-end; see popover placement types).
showArrowbooleantrueShow the chevron indicator. When singleClickAction is set, the chevron is always shown (this prop is effectively ignored in split mode).
searchablebooleanfalseShow 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.
iconOnlybooleanfalseHide 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 items as 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; -start and -end align to its ends. Menus stay within the viewport.
  • The dropdown uses the same ContextMenu overlay, so it requires provideContextMenu() (or setupOverlays()) in a parent layout.
  • Set showArrow={false} to hide the chevron for a cleaner look (not used when singleClickAction is set).
  • All six variants match Button: primary uses the dim accent surface, secondary uses the base surface, outline adds a border, danger uses danger colors, and ghost and link use 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, and lg sizes use the shared CSS control-height and icon-size tokens, matching Button. fullWidth stretches 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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.