On this page
@addTagHelper *, Webority.Ui.RazorIcons and shortcuts
Give items an icon or a key so the menu scans quickly.
Destructive and disabled
Place a danger item last, and give a disabled item a reason the person can read on hover or focus.
Posting and responsive
Let a menu item post a quick change, and hide a duplicate control on wide screens where the toolbar shows it.
Grouping
Group related items under a divider or a heading, so a long menu reads in clear parts.
Custom trigger
Use a custom trigger for an account chip or a button-style menu; the trigger replaces the default icon.
Rich content
Put any markup inside the menu and it renders verbatim: an identity block, a form, anything that isn't a flat action list.
Alignment
Open the menu from the end by default, and from the start when the trigger sits at the left edge.
Search a long menu
Set searchable and a search box sits above the rows, filtering them by label as the user types.
Open motion (product-level)
Every menu-like overlay (dropdowns, popovers, the select, date and phone panels) shares one entrance animation from the theme. It is a product-level choice on the root element, not a per-component attribute. Set <html data-wui-menu-motion="drop"> to pick: drop (zoom, fade and a 6px drop out of the trigger, the default), zoom (zoom and fade only, the quietest), spring (elastic overshoot), unfold (scales open vertically like a sheet) or none (no entrance). Menus that flip upward animate from their bottom edge automatically, and everything is disabled under prefers-reduced-motion.
Every option
Every value of every prop, one cell each.
icon: four glyphs
icon="more-horizontal"
icon="settings"
icon="user"
icon="plus"
items: row kinds
<button class="dropdown-item"> (React: { label, onClick })
<app-dropdown-item icon="edit"> (React: { icon })
<app-dropdown-item image="…"> (React: { image })
<app-dropdown-item tone="danger"> (React: { tone: "danger" })
<hr class="dropdown-divider"> (React: { divider: true })
<app-dropdown-header> (React: { header })
description="…" (React: { description })
shortcut="Enter" (React: { shortcut })
disabled="true" disabled-reason="…" (React: disabled, disabledReason)
hidden-from="md" (React: hiddenFrom: "md")
href="/Components/AppButton" (React: { to })
action="?handler=Snooze" confirm="Move this to tomorrow?" (React: onClick)
no rows (React: items={[]})
ariaLabel: names the toggle
aria-label="Row actions"
align: both values
align="end" (default)
align="start"
iconSize: glyph size
icon-size="32"
toggleClassName: button-style trigger
toggle-class="btn btn-primary"
toggleVariant: neutral trigger
toggle-variant unset (default)
toggle-variant="neutral"
menuWidth: fixed widths and fit
menu-width unset (default)
menu-width="sm"
menu-width="md"
menu-width="lg"
menu-width="fit"
menuClassName: panel class
menu-class="my-menu" (adds a class to the panel; no visible change here)
linkComponent: router links
href: a link row (React: linkComponent renders to items)
searchable: long menu
searchable unset (default)
searchable="true"
searchPlaceholder: search box label
search-placeholder="Find a project"
noMatchText: empty search result
no-match-text="Nothing matches" (type in the search box to see it)
label: toggle tooltip and name
label="Row actions"
children: rich content
(content): any markup in place of rows
trigger: custom toggle
<app-dropdown-toggle> (React: trigger, replaces the icon)
open: controlled state
open unset (default)
open={true} (React only: Razor has no controlled open)
onOpenChange: open and close requests
onOpenChange (React only: Razor has no open event; no visible change)
Guidance
What to do, and what to avoid.
Use it when
- A row or card has several secondary actions that would clutter the layout as buttons.
- You want a consistent “⋯” affordance for overflow actions across every row.
- The actions are related and belong under one grouped trigger.
- A menu lists more than about ten rows and the user knows the name of the one they want.
Reach for something else when
- There is a single icon action. → AppActionIcon
- The action is the primary thing on the screen. → AppButton
- You are selecting one value from a list. → AppSelect
- You need a yes/no confirmation. → AppConfirmDialog
Put the destructive item last
Overflow actions collapse into one trigger, with the destructive one marked danger and placed last.
Delete sits first and unmarked, so it looks like every other item and is the easiest to hit by mistake.
Keep the menu short and clear
A short, scannable list of clearly worded actions.
A menu with nine items becomes a wall to read. Group or split it, or promote the common ones out.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
21 props. The 4 most used come first.
Used on most screens 4 props
| Prop | Type | Default | Description |
|---|---|---|---|
| icondefault more-horizontal | string | more-horizontal | Name of the glyph on the toggle button. A custom trigger replaces it. |
| aligndefault end | start | end | end | Which edge of the toggle the menu lines up with. |
| aria-labeldefault - | string | - | Accessible name of the toggle; it wins over label. |
| menu-widthdefault - | sm | md | lg | fit | - | A fixed menu width (15, 20 or 25rem; long rows wrap instead of widening the menu), or fit: no minimum, the menu is as wide as its widest row. Unset, the menu is at least 12rem wide. |
Less common 17 props
| Prop | Type | Default | Description |
|---|---|---|---|
| (content)default - | markup | - | The menu items: one button for each action (an a element for navigation), or app-dropdown-item rows. |
| app-dropdown-itemdefault - | child | - | A row: href (a link; otherwise a button), icon, image, tone, description, a muted second line under the label, and shortcut, the key that runs it, drawn as a key chip at the end and named in aria-keyshortcuts. Its content is the label; other attributes land on the row. |
| hidden-fromdefault - | sm | md | lg | xl | - | On an app-dropdown-item: the row hides from that width up, so the overflow menu absorbs it on narrow screens. An unknown value throws. |
| actiondefault - | string | - | On an app-dropdown-item: posts here when chosen, with the antiforgery token; the answer toasts like a row action (Razor only). |
| confirmdefault - | string | - | With action: ask this first. |
| app-dropdown-item-valuedefault - | slot | - | A hidden field the item posts (name, value). |
| app-dropdown-headerdefault - | child | - | A group heading between rows. Its content is the heading text. |
| labeldefault Menu | string | Menu | Tooltip and accessible name fallback for the toggle. |
| icon-sizedefault 20 | int | 20 | Size of the toggle glyph in pixels. |
| toggle-classdefault topbar-icon-btn | string | topbar-icon-btn | Class for the toggle button, replacing the default. Give it a button look, such as a primary button, for a button-styled trigger. |
| toggle-variantdefault - | neutral | - | neutral: a custom trigger that keeps the surrounding font and colour, with a muted fill on hover and while open. Needs an app-dropdown-toggle child. |
| tone (app-dropdown-toggle)default Primary | Primary | Success | Warning | Danger | Info | Neutral | Primary | On app-dropdown-toggle: draws the trigger as an app-button of this tone. Setting tone or variant replaces the plain trigger look; not with toggle-class on the dropdown. |
| variant (app-dropdown-toggle)default Solid | Solid | Soft | Outline | Ghost | Link | Glass | Solid | On app-dropdown-toggle: the trigger's fill. Link draws it as a text link. |
| searchabledefault false | bool | false | Puts a search box above the rows that filters them by label as the user types, for a long menu. It filters items, so it cannot be combined with children. |
| search-placeholderdefault Search | string | Search | Placeholder and accessible name of the search box. Needs searchable. |
| no-match-textdefault No matches. | string | No matches. | Text shown when no row matches the search. Needs searchable. |
| menu-classdefault - | string | - | Extra class on the menu container, added after its own classes. |
Screen reader
3 notes- The toggle is a button named by ariaLabel, else by label; an icon-only toggle with neither is an unnamed button, and a development warning says so.
- The menu closes on an outside click or Escape and moves between items with the arrow keys, and a custom trigger keeps all of it.
- An item with a shortcut names its key to assistive technology through aria-keyshortcuts; picture rows use empty alt text.
Do and avoid
2 pairsPut the destructive item last
Overflow actions collapse into one trigger, with the destructive one marked danger and placed last.
Delete sits first and unmarked, so it looks like every other item and is the easiest to hit by mistake.
Keep the menu short and clear
A short, scannable list of clearly worded actions.
A menu with nine items becomes a wall to read. Group or split it, or promote the common ones out.