An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:DropdownMenu authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-31 owners: [cixzhang] review_triggers: [accessibility, behavior, layout, public-api, theming] verified_by: [ packages/core/src/DropdownMenu/DropdownMenu.test.tsx, packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx, packages/core/src/DropdownMenu/tests/DropdownMenuDrillIn.a11y.chromium.spec.ts, packages/core/src/DropdownMenu/tests/MenuPress.a11y.chromium.spec.ts, packages/core/src/DropdownMenu/tests/MenuHeaderFooter.a11y.chromium.spec.ts, packages/core/src/DropdownMenu/tests/SubMenuHeaderFooter.a11y.chromium.spec.ts, packages/core/src/ContextMenu/ContextMenu.test.tsx, packages/core/src/theme/themingTargets.test.ts, scripts/check-knowledge.mjs, ] modules: [module:DropdownMenu/useMenuPress, module:DropdownMenu/useMenuHover] families: [family:overlay-dismissal, family:navigation-destinations] design_specs: [design:reduced-motion] architecture: [ architecture:component-theming-surface, architecture:interaction-modality, architecture:layer-runtime, ] contributing: []
system_specs: [spec:AST-020/FR15, spec:AST-094, spec:AST-102]
DropdownMenu component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | None changes. DropdownMenu takes a button (Button props) or renderTrigger, data-driven items or compound children, presentation, isMenuOpen and onOpenChange, placement and alignment, menuMaxHeight, header, and footer. |
| Behavior | A Menu Button trigger opens an anchored pointer menu or a bottom-sheet action list. Rows act on the release under the shared press model; sub-menus fly out beside their row or drill in on a compact touch display; a header or footer makes the pointer popover a modal dialog around the menu. |
| End-user impact | People pick actions by mouse, finger, or keyboard; keyboard users get a focus return with a ring and pointer users without one; on a phone sub-menus replace the rows instead of flying off-screen. Under a finger the menu opens after a 500 ms hold or at a tap's click, does not grow from its trigger, and a pan outside does not close it. |
| Builder impact | Builders choose the trigger, the rows, and the regions; rows stay menu items and every non-item control goes in header or footer. |
| Compatibility/readiness | Records shipped behavior; no API change; a disabled row gains tabindex="-1"; the released behavior under a finger moves as spec:AST-094 FR25 lists, with presentation="popover" keeping it. Finger press-open (FR8), touch grow and pan dismissal (FR21), the still mouse (FR22), and Trigger Button gaps are in Current-state impact. |
| Review checks | Reject a control placed among the rows, a lost trigger ARIA wiring, a drilled-in view that leaves the menu box, a header or footer without the dialog, a lost focus-return modality, or a target moved off its painted element. |
| Governing rules | spec:AST-020 FR15; spec:AST-094 FR26–FR35; module:DropdownMenu/useMenuPress; architecture:interaction-modality INV1; architecture:component-theming-surface; architecture:layer-runtime; family:overlay-dismissal; family:navigation-destinations. |
This table is a review projection; the body below is authoritative.
Intent
DropdownMenu presents actions from a visible trigger in either an anchored
pointer menu or a BottomSheet-hosted touch action list. Its press model — the
row under the release acts and the highlight follows the pointer — is
contracted by module:DropdownMenu/useMenuPress, which both presentations
mount.
Compatibility and migration
- Released default preserved:
nounder a finger: the omittedpresentationfollowsspec:AST-094FR29, FR31, and FR32 (FR8, FR21);presentation="popover"keeps the released behavior (spec:AST-094FR25); andnofor disabled rows on every pointer: the keyboard reaches a disabled row and the row carriestabindex="-1"(FR17), a defect fix under DEC-11 (owner decision, 2026-11-04) - Compatibility class: records shipped behavior; no public prop or export
change; a disabled row gains
tabindex="-1"(FR17) - Controlled/uncontrolled behavior:
isMenuOpenwithonOpenChange, or uncontrolled - Migration decision:
spec:AST-094FR25 and DEC-4
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The Pointer menu surface and Touch menu surface and their shared
dropdown-menutarget. - Pointer action rows, pointer-only section headings and dividers, radio marker specialization, and submenu indicator presentation through the other five DropdownMenu targets.
- Selecting between the pointer and touch render paths after presentation policy resolves.
- Mounting the shared press model on both menu surfaces and on the Trigger
button; the model itself is owned by
module:DropdownMenu/useMenuPress. - The
headerandfooterregions, the dialog around them, and the drilled-in view.
Does not own / non-goals
- Trigger-button presentation — delegated to
component:Button. - The Touch sheet frame — delegated to
component:BottomSheet. - Touch action-list and row presentation — delegated to
component:List. - Shared checkbox-indicator and ordinary icon presentation — delegated to
component:Indicatorandcomponent:Icon. - Each row's own contract — owned by
component:DropdownMenuItem,component:DropdownMenuCheckboxItem,component:DropdownMenuRadioGroup,component:DropdownMenuRadioItem,component:DropdownMenuSubMenu,component:DropdownMenuGroup, andcomponent:DropdownMenuDivider. - The flyout hover timing — owned by the menu hover module (
useMenuHover). - Shared layer lifecycle or dismissal policy.
Public concepts
Consumer props, item shapes, subcomponents, and presentation policy remain
documented in DropdownMenu.doc.mjs and the subcomponent docs. These are the
component-local concepts; each keeps its released default.
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Menu height cap | menuMaxHeight: a number of pixels |
Lifts the 300px cap for a menu that must fit its rows; the viewport still bounds it. | Pointer presentation | 300px |
component:DropdownMenu |
stable | Ignored by the touch sheet. |
| Trigger source | button (Button props) or renderTrigger (render prop) |
Which control the menu hangs off. renderTrigger receives DropdownMenuTriggerProps — the press model, keyboard opens, toggle click and ARIA wiring — and names the menu. |
Both presentations | button |
component:DropdownMenu |
stable | Both given: renderTrigger wins and a dev warning fires. |
| Header and footer | header, footer: any React node |
Content above and below the rows, beside the menu inside the same popover or sheet — never inside the role="menu" element. With either, the pointer popover is a modal dialog around the menu. |
Both presentations | none | component:DropdownMenu |
stable | A false or empty value renders no region. |
| Sub-menu regions | header, footer on a sub-menu: any React node |
Content above and below a sub-menu's rows, beside its menu inside its own surface; with either, that surface is a modal dialog named by the row (FR20). | Popover presentation | none | component:DropdownMenu |
stable | A false or empty value renders no region. |
| Row destination | href (+ target, rel) on an action item |
The row's act is navigation: the row itself is the link (family:navigation-destinations). |
Pointer action row and Touch action row, compound and data mode | none (an action row) | component:DropdownMenu |
stable | Blocked schemes follow the family rule; a disabled row has none. |
| Sub-menu presentation | presentation on a sub-menu row: flyout, drill-in, adaptive |
Whether a sub-menu opens beside its row or replaces the menu's rows with its own and a Back row, in the same box. adaptive drills in when a compact touch display opened the menu. |
Pointer presentation, compound and data mode | adaptive |
component:DropdownMenu |
stable | An unknown value reads as adaptive. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Every render contains a Trigger button. Pointer presentation renders a Pointer menu surface with pointer-owned rows and optional pointer headings, dividers, indicators, and nested flyouts. Touch presentation renders a Touch sheet frame containing a Touch menu surface, Touch heading, Touch action list, and Touch action rows. | Current source, docs, and tests |
| FR2 | The six local targets are dropdown-menu, dropdown-menu-item, dropdown-menu-radio, dropdown-menu-section-heading, dropdown-menu-divider, and dropdown-menu-indicator-icon; every target stays on its painted element. |
architecture:component-theming-surface; current source |
| FR3 | Button owns the Trigger button, BottomSheet owns the Touch sheet frame, List owns the Touch action list and Touch action rows, Indicator owns checkbox chrome, and Icon owns ordinary rendered icons. The Trigger button carries component:Button's gaps: its press scale applies under reduced motion (design:reduced-motion DR1) and its height is fixed (spec:AST-102 FR4). |
Current source and owner docs; design:reduced-motion DR1; spec:AST-102 FR4 |
| FR4 | The same dropdown-menu target reaches the alternative Pointer menu surface and Touch menu surface. Pointer action rows carry dropdown-menu-item; touch action rows instead use List's list-item target. |
Current source and tests |
| FR5 | Both menu surfaces carry data-astryx-menu-press and follow module:DropdownMenu/useMenuPress FR1–FR7, FR10, and FR11: the row under the release acts, the highlight follows a held pointer, a mouse released outside closes and a finger leaves the menu open, the browser's stray click never acts, and the Pointer menu surface declares touch-action by overflow. The grow, collapse, and pan dismissal under a finger are FR21. |
module:DropdownMenu/useMenuPress; spec:AST-094 FR26–FR28 |
| FR6 | When the pointer menu closes, focus returns to the Trigger button with a visible ring only when the menu was driven by keyboard, and after a pointer pick the returned focus opens no trigger tooltip (component:Tooltip FR4); a press outside that landed on a focusable control keeps focus there. |
architecture:interaction-modality INV1; DEC-1 |
| FR7 | menuMaxHeight replaces the 300px term of the menu's and its popover viewport's block-size cap while the viewport gutters still bound both; the touch sheet ignores it. |
DEC-2 |
| FR8 | The Trigger button opens the pointer menu on a mouse press-down, with a settle rule on the opening release, and pressing the trigger of an open menu closes it without reopening in the same gesture; a mouse click and the keyboard open as before. The mouse press-open is shipped behavior, not a requirement until module:DropdownMenu/useMenuPress DEC-4 is ruled. Under a finger the trigger MUST open the menu as spec:AST-094 FR29 states: as the finger presses in a fixed bar, after the 150 ms content-touch delay or at a tap's lift inside a scroll view; presentation="popover" keeps the tap open. Implementation gap: a held finger opens it after a 500 ms hold, and a tap opens it at its click. |
module:DropdownMenu/useMenuPress FR8, FR9; spec:AST-094 FR29 |
| FR9 | With renderTrigger, the rendered control carries aria-haspopup, aria-expanded, aria-controls and the id the menu's aria-labelledby points at, and receives the same press-model, keyboard-open and toggle-click handlers as the Button path; the menu is named by that control. A disabled custom trigger never opens the menu or the sheet. button and renderTrigger are mutually exclusive: both given, renderTrigger wins and a dev warning fires, in both presentations. A drilled-in Back row (FR11) returns to the menu by that same name: the caller's aria-label when given, else the control's accessible name, read as the menu opens. |
DEC-3 |
| FR10 | An action row with href renders as one anchor carrying role="menuitem" (the pointer menu) or the touch sheet's link row, routed through LinkProvider; a plain click runs onClick, then closes the menu (hasCloseOnSelect), then lets the browser navigate; a modified click does not run onClick, closes the menu, and is left to the browser; in the pointer menu a middle click closes the menu (hasCloseOnSelect), then runs the caller's onAuxClick, while the touch sheet leaves a middle click to the browser and stays open; a right click is left to the context menu; Enter and Space activate through a synthesized click that carries the key's modifiers. A disabled link row has no href; a blocked destination renders inertly. |
Current behavior; family:navigation-destinations |
| FR11 | When a compact touch display opened the pointer menu (the query the root presentation uses for its bottom sheet, sampled once as it opens), an adaptive sub-menu row drills in: its rows and a leading Back row named "Back to " replace the menu's rows in the same Pointer menu surface, no flyout opens, the drilled list is a menu named by the row's label, and Back, Escape and ArrowLeft return to the row with focus on it; a pick inside closes the whole menu, and closing the menu resets the drilled view. Roving focus and typeahead scope to the shown rows; sibling rows and dividers need no knowledge of it. presentation="flyout" keeps the flyout; "drill-in" drills in on any pointer. |
DEC-4; spec:AST-094 FR34 |
| FR12 | In the pointer menu ArrowDown on the last row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp move to the last and first fully visible row and, pressed there again, one viewport further without wrapping; disabled rows count as rows for every one of these keys (FR17); ArrowUp on the trigger opens with the last enabled row highlighted; the key that opened the menu and its auto-repeats do not activate; typeahead matches the row's label element alone and ignores Control/Command chords and input-method composition. | Current source and tests |
| FR13 | On a mouse, a nested flyout stays open while the pointer is inside the triangle from where it left its row to the flyout's near edge — including while the pointer is paused there — and closes after the existing delay once the pointer has left both the row and that triangle. The row's click toggle and its guard window are unchanged. | Current behavior |
| FR14 | Compound groups follow component:DropdownMenuGroup; a data-mode {type: 'section'} entry is a role="group" named by its title, and an untitled section renders its rows without a heading. |
DEC-6; current tests |
| FR15 | With header or footer, the pointer popover is a role="dialog" with aria-modal="true", named like the menu, holding the header, then the role="menu" element, then the footer; the menu element holds only its rows. The trigger says aria-haspopup="dialog" and its aria-controls names the popover that holds the dialog. A region keeps its own keys and presses: neither the menu's key handling nor its press model claims an event that begins there. The menu is one Tab stop between the regions. Tab and Shift+Tab move through the header's controls, the menu, then the footer's controls, and wrap at either end; a control that is hidden, or under a hidden ancestor within its region, is not a stop. From a row, or a row of an open sub-menu, Tab and Shift+Tab close every open flyout and continue from the menu's stop. With no other stop, focus stays in the menu. Escape closes from anywhere in the popover, and focus returns to the trigger. The bottom sheet, already a dialog, shows the header above the actions and the footer below them. Without either prop, the menu renders and behaves exactly as it does without them: no dialog, aria-haspopup="menu", and Tab closes the menu. |
DEC-8, DEC-10 |
| FR16 | Checkbox rows follow component:DropdownMenuCheckboxItem. |
Current source |
| FR17 | A disabled menu row MUST be reached by the keyboard and stay inert (DEC-11): in DropdownMenu, its sub-menus, MoreMenu, ContextMenu and NavHeadingMenu, ArrowDown, ArrowUp, Home, End and type-ahead visit a disabled row as they visit any other row, the row takes focus and exposes aria-disabled="true", and Enter, Space or a click on it does nothing and leaves the menu open. Opening a menu from the keyboard still lands on an enabled row: the first, or the last after ArrowUp on the trigger (FR12, AR4). |
DEC-11; WAI-ARIA Menu pattern |
| FR20 | With header or footer on a sub-menu (DropdownMenuSubMenu), its surface is a modal dialog named by its row (AR7), holding the header, the sub-menu's role="menu" (rows only), then the footer. It sits in a host DropdownMenu renders beside its menu, never inside a menu; under a root with no such host (ContextMenu) the sub-menu shows its rows alone. On a fine pointer the dialog is the flyout; on a compact touch display, the drilled-in view, which replaces the root's menu and regions until popped. A region keeps its own keys and presses. The rows are one Tab stop: Tab and Shift+Tab walk the header's controls, the rows, then the footer's, and wrap; from a deeper flyout, that flyout closes and the walk goes on from the rows. An open lands as for any sub-menu (FR11, FR12), not on a region. Escape in the dialog, outside an IME composition and unless a control there handled it, returns focus to the row and leaves the root open. A pointer leaving the flyout keeps it open until focus leaves, and it closes with the flyout holding its row. Without either prop nothing changes. |
Current behavior; FR15; AR5 |
| FR21 | Under a finger, in the touch modes (presentation not pinned to 'popover'), the pointer menu MUST grow out of the Trigger button on the theme's entrance duration and easing tokens and collapse back into it on the theme's exit duration and easing (spec:AST-094 FR7, FR31, FR45), and MUST close as a pan that starts outside it begins (FR32); a pinned 'popover' keeps the layer's own entrance. A pan dismissal is the menu's own close: focus that was in the menu returns to the Trigger button, whose aria-expanded turns false. A mouse keeps the layer's own entrance and exit. Implementation gap: the menu keeps the layer's own entrance and exit under a finger too, and has no pan-outside dismissal of its own. |
spec:AST-094 FR31, FR32; family:overlay-dismissal AV6 |
| FR22 | Under a finger, in the touch modes, where the primary pointer is coarse (a phone or a tablet), a tap or a drag that lands while the pointer menu enters MUST reach nothing: it closes nothing, scrolls nothing, moves no focus and clicks nothing (spec:AST-094 FR35). The finger that opened the menu still picks the row it lifts on (FR8). Keys and assistive technology stay live. A mouse, a pinned 'popover' and a finger where the primary pointer is fine (a touchscreen laptop) hold nothing, as for component:Drawer. Implementation gap: after a finger, a still mouse's first press lands on the entering menu's shield unless the mouse rests where the page last heard it when the shield came up (spec:AST-094 FR35). |
spec:AST-094 FR35; architecture:layer-runtime |
| FR23 | Tab or Shift+Tab on a row at any level of a menu without header or footer, its own rows or an open sub-menu flyout's at any depth, closes every open level and the menu, calls onOpenChange(false) once, and leaves focus to move on from the trigger in page order (WAI-ARIA Menu Button). A level with a header or footer keeps FR15's and FR20's Tab cycle within it. |
WAI-ARIA Menu Button pattern; current tests |
Allowed variation
- AV1 — Presentation.
popover,bottom-sheet, and resolvedadaptivepresentation may select the pointer or touch anatomy without changing the ownership of either branch. - AV2 — Content mode. Data-driven and compound pointer menus may vary their rows while preserving the target owners. Touch presentation remains data-driven.
- AV3 — Optional content. Icons, selectable indicators, headings, dividers, and nested actions render only when the supplied menu content requires them.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Anchored root menu | Trigger button and Pointer menu surface render with pointer-owned rows. | Width, placement, alignment, and optional item content vary. |
| Anchored nested flyout | Pointer action row opens another Pointer menu surface and may show the submenu indicator icon. | Loading may replace the indicator with the Spinner. |
| Drilled-in sub-menu | The Pointer menu surface shows a Back row then the sub-menu's rows; the parent rows are hidden, not unmounted. | Depth; which pointer opened the menu; a forced presentation. |
| Bottom-sheet root actions | Trigger button opens Touch sheet frame, Touch menu surface, heading, action list, and action rows. | Icons, sections, dividers, and action descriptions may vary. |
| Bottom-sheet nested actions | The same frame and list owners remain while heading and rows change to the selected action level. | Back control and drill-in indicator follow navigation. |
| Selectable pointer action | Pointer action row may contain shared checkbox or radio chrome. | Checked and disabled state follow the item contracts. |
| Custom-trigger menu | The caller's control carries the trigger ARIA and names the menu; the Pointer menu surface is unchanged. | Any focusable control: icon button, chip, avatar, list row. |
| Link row | The Pointer action row (or Touch action row) is the anchor; onClick, close and navigation run in that order on a plain click. |
target, rel, icon, description and destructive variant vary. |
| Header or footer | The popover is a named modal dialog holding header, menu, and footer; Tab wraps. | Region content. |
Transformation and precedence order
- ORD1 — Link row activation. modified click → no
onClick, close (hasCloseOnSelect), the browser opens it; elseonClick→ close (hasCloseOnSelect) → the browser navigates. - ORD2 — Trigger source.
renderTrigger→button.
Performance and resources
- PR1 — Bounded resources. While open, the pointer menu observes its own
size and content changes and listens for window and visual-viewport resizes
and image loads to decide whether it scrolls. A press-open, by a mouse press or a
held finger, adds document pointer-up and pointer-cancel listeners for the
length of the press. With
presentation="adaptive"the root subscribes to the compact-touch query while mounted; the drill-in reads it once as the menu opens.
Accessibility contract
While a pointer is held, the highlight is DOM focus per
module:DropdownMenu/useMenuPress AR1. Focus return on close follows FR6 and
architecture:interaction-modality INV1 through the shared focus-return
visibility helper.
- AR1 — A custom trigger still names the menu. With
renderTrigger, the menu carriesaria-labelledbypointing at the control'sid(the Button path keepsaria-label), and the control carriesaria-haspopup="menu",aria-expandedandaria-controls. - AR2 — A row that navigates is a link element. A row with an
hrefis the anchor itself: in the pointer menu it keepsrole="menuitem"so the menu stays one menu, while a modified click or Enter keeps the browser's link meaning; in the bottom sheet the row is a plain link; a disabled link row is not activatable. - AR3 — A drilled-in sub-menu stays one menu. On a compact touch display a
sub-menu replaces the rows in the same menu box with a "Back to " row
and its own rows; after a keyboard open focus lands on the first enabled row
after Back, after a pointer open on the drilled list (the
menu); Back, Escape, or ArrowLeft return to the parent view with focus restored. - AR4 — The anchored trigger adopts the APG Menu Button pattern's required
parts (
spec:AST-020/FR15): the control that opens the anchored pointer menu is abuttonwith an accessible name,aria-haspopup="menu",aria-expandedreflecting the menu, andaria-controlsnaming it; Enter or Space opens the menu with focus on the first enabled row. As a named exception under that rule, the trigger also opens on ArrowDown (focus on the first enabled row) and ArrowUp (focus on the last enabled row), the keyboard this component already ships (DEC-9). ArenderTriggercontrol receivesaria-haspopup,aria-expanded,aria-controls, and the keyboard and focus handlers through the spread props (FR9); the caller's control supplies its ownbuttonrole and accessible name. The bottom-sheet presentation and a pointer menu withheaderorfooterare outside this pattern: their trigger opens a dialog and saysaria-haspopup="dialog"(AR5). - AR5 — With a header or footer, the pointer popover adopts the APG Dialog
(Modal) pattern's required parts (
spec:AST-020/FR15):role="dialog",aria-modal="true", and an accessible name, the menu's; focus moves into the dialog on open, to the menu or its first enabled row as FR6 and FR12 state; Tab and Shift+Tab cycle within it (FR15); Escape closes it and focus returns to the trigger. The menu inside keeps AR1–AR3. The trigger keepsaria-expanded; itsaria-haspopupsaysdialog, and itsaria-controlsnames the popover that holds the dialog rather than the menu, as Popover's own trigger does. - AR6 — Disabled rows are inert. A disabled row runs no caller activation handler and does not close the menu; FR17 records that the keyboard reaches it.
- AR7 — A sub-menu with a header or footer adopts the same APG Dialog
(Modal) parts for its own surface (
spec:AST-020/FR15):role="dialog",aria-modal="true", and an accessible name, its row's; focus moves into the dialog on open, to the sub-menu's first enabled row or its menu as FR11 and FR12 state; Tab and Shift+Tab cycle within it (FR20); Escape closes it and focus returns to the row. The sub-menu's menu inside keeps AR3. The row keepsaria-expanded; itsaria-haspopupsaysdialogand itsaria-controlsnames the dialog.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Trigger button | Provides the visible control that opens and closes the selected presentation. | component:Button |
Supporting | FR1, FR3 |
| Trigger indicator icon | Communicates disclosure on labeled triggers when enabled. | component:Icon |
Supporting | FR1, FR3 |
| Pointer menu surface | Paints the anchored root or nested pointer menu panel. | Current source and public docs | Prominent | FR1, FR2, FR4 |
| Pointer action row | Presents one action, selectable option, or nested-menu entry. | Current source and public docs | Prominent | FR1, FR2, FR4 |
| Icon-rendered item icon | Adds an optional semantic or component icon to an action row through Icon. | component:Icon |
Supporting | FR1, FR3 |
| Caller-rendered item start content | Presents arbitrary React content directly in an action-row start slot. | Caller-supplied content | Context-dependent | FR1, FR3 |
| Checkbox indicator | Draws the decorative checkbox state for a checkbox action row. | component:Indicator |
Supporting | FR1, FR3 |
| Radio indicator | Draws shared radio chrome with the current menu-specific radio target. | Current source and Indicator | Supporting | FR1, FR2, FR3 |
| Pointer section heading | Labels a grouped set of pointer action rows. | Current source and public docs | Supporting | FR1, FR2 |
| Pointer divider | Separates groups of pointer action rows. | Current source and public docs | Supporting | FR1, FR2 |
| Pointer submenu indicator icon | Identifies a pointer action row that opens a nested flyout. | Current source and public docs | Supporting | FR1, FR2 |
| Touch sheet frame | Supplies the touch panel, scrolling area, handle, and optional scrim. | component:BottomSheet |
Prominent | FR1, FR3 |
| Touch menu surface | Arranges menu-owned heading and action content inside the sheet. | Current source and public docs | Prominent | FR1, FR2, FR4 |
| Touch heading | Names the current root or drill-in action view. | Current source and tests | Supporting | FR1 |
| Touch action list | Groups touch actions using the spacious List presentation. | component:List |
Prominent | FR1, FR3 |
| Touch action row | Presents one touch action or drill-in entry using ListItem. | component:List |
Prominent | FR1, FR3, FR4 |
| Touch divider | Separates groups in the touch action list. | component:Divider |
Supporting | FR1, FR3 |
The dropdown-menu target intentionally appears on both alternative menu
surfaces. The radio element also carries Indicator's shared radio target, and
the pointer divider also carries Divider's target; their local targets remain
valid distinct contracts. Touch headings retain the shared heading target documented by Text rather
than adding a DropdownMenu-owned heading target.
Theming anatomy
{
"Trigger button": {
"delegatesTo": {"owner": "component:Button", "target": "button"}
},
"Trigger indicator icon": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Pointer menu surface": {"target": "dropdown-menu"},
"Pointer action row": {"target": "dropdown-menu-item"},
"Icon-rendered item icon": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Caller-rendered item start content": {
"none": {
"reason": "intentional: Arbitrary ReactNode item content is caller-owned and receives no DropdownMenu target."
}
},
"Checkbox indicator": {
"delegatesTo": {
"owner": "component:Indicator",
"target": "checkbox-indicator"
}
},
"Radio indicator": {"target": "dropdown-menu-radio"},
"Pointer section heading": {"target": "dropdown-menu-section-heading"},
"Pointer divider": {"target": "dropdown-menu-divider"},
"Pointer submenu indicator icon": {
"target": "dropdown-menu-indicator-icon"
},
"Touch sheet frame": {
"delegatesTo": {"owner": "component:BottomSheet", "target": "bottom-sheet"}
},
"Touch menu surface": {"target": "dropdown-menu"},
"Touch heading": {
"delegatesTo": {"owner": "component:Text", "target": "heading"}
},
"Touch action list": {
"delegatesTo": {"owner": "component:List", "target": "list"}
},
"Touch action row": {
"delegatesTo": {"owner": "component:List", "target": "list-item"}
},
"Touch divider": {
"delegatesTo": {"owner": "component:Divider", "target": "divider"}
}
}
Family and system relationships
architecture:component-theming-surfaceowns anatomy qualification, local target mapping, presentation-specific rows, and delegation rules.architecture:interaction-modalityowns the shared pointer, touch, keyboard, and adaptive-presentation boundaries.architecture:layer-runtimeowns the popover host, native light-dismiss reconciliation, anchor positioning, and nested flyout layers. Touch presentation delegates hosting to BottomSheet.family:overlay-dismissalowns shared Escape and platform-close ordering. The DropdownMenu root participates through its popover focus trap; the composed BottomSheet and DropdownMenuSubMenu retain their recorded local-only adoption gaps.family:navigation-destinationsowns link-row destinations and blocked schemes (FR10).spec:AST-094owns the touch press, open, grow, entrance, and dismissal rules (FR5, FR8, FR11, FR21, FR22).
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR4 | DropdownMenu.test.tsx rendering cases ("renders menu with role="menu"", "renders data-driven actions in a bottom sheet when requested", "uses the BottomSheet for adaptive presentation on compact touch", "uses the shared menu BottomSheet frame", "keeps adaptive presentation anchored without compact touch") and section, divider, and compound cases |
Root pointer, root touch, adaptive | A missing surface, sheet frame, or menu role fails. Evidence gap: no test asserts the dropdown-menu target on the Touch menu surface or list-item on touch rows. |
audit:DropdownMenu/anatomy |
| FR2 | DropdownMenu.test.tsx theming-slot cases ("exposes a themeable slot on the section heading", "exposes a themeable slot on the menu divider"); DropdownMenuSubMenu.test.tsx "exposes a themeable slot on the submenu indicator icon"; themingTargets.test.ts |
Heading, divider, submenu indicator | A missing heading, divider, or indicator target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts dropdown-menu, dropdown-menu-item, or dropdown-menu-radio placement. |
audit:DropdownMenu/theming |
| FR3 | DropdownMenu.test.tsx button customization, icon-only, and hasChevron cases |
Button variants and sizes; icon-only; no chevron | A Button prop that stops reaching the trigger fails. Evidence gap: the delegated Trigger Button gaps are asserted by component:Button's own records, and no test here asserts the BottomSheet, List, Indicator, or Icon delegation beyond rendering. |
audit:DropdownMenu/theming |
| FR5 | DropdownMenu.test.tsx press-model cases ("a finger that lands on one row and lifts on another acts on the second, once", "a mouse released outside closes the menu; a finger released outside leaves it open", "marks the menu as carrying the press model and owns touch scrolling"); MenuPress.a11y.chromium.spec.ts; the module record's own map |
Finger and mouse release; scrolling menu | A row that acts on press-down, a mouse release outside that keeps the menu, or a missing press marker fails. | audit:DropdownMenu/behavior |
| FR6 | DropdownMenu.test.tsx focus-return cases ("restores focus to the trigger after keyboard dismissal", "returns focus to the trigger after pointer dismissal without a focus ring", "leaves focus on the control a press outside landed on") and the "focus return after a pointer pick" and "a trigger the caller renders" cases |
Keyboard and pointer close; Button and custom trigger | A lost focus return, a ring after a pointer close, no ring after a keyboard close, or focus pulled off a control pressed outside fails. | audit:DropdownMenu/accessibility |
| FR7 | DropdownMenu.test.tsx menuMaxHeight cases |
A cap above 300px; viewport bound | A menu clipped to 300px under a raised cap, or one that escapes the viewport, fails. Evidence gap: no test asserts that the touch sheet ignores the cap. | audit:DropdownMenu/layout |
| FR8 | DropdownMenu.test.tsx press-model trigger cases ("a mouse press on the trigger opens the menu and a drag-release acts on the row under it", "the opening release before the settle time acts on nothing and the menu stays", "pressing the trigger of an open menu closes it and does not reopen it in the same gesture", "a held touch on the trigger opens with the finger down and a slide picks", "a tap on the trigger still opens through its click") |
Mouse press-open; held finger; tap | A mouse that opens only on click, an opening release that acts early, or a re-open in the closing gesture fails. The held-touch case asserts the current 500 ms hold, the FR8 gap pending conformance. | audit:DropdownMenu/behavior |
| FR8 | DropdownMenuOpeningRelease.interaction.browser.spec.ts (Chromium, WebKit): an opening release off the trigger, under a trigger that moved away, or on the trigger after a show that waited leaves the menu open; a settled release outside closes it |
Mouse release off the trigger | An opening release before the settle time that the browser's light dismiss closes fails | audit:DropdownMenu/behavior |
| FR9, AR1 | DropdownMenu.test.tsx custom trigger cases; DropdownMenuSubMenu.test.tsx "a menu hung off a custom trigger" cases |
Custom trigger open, keyboard, mouse, disabled; both props given; Back row names | A custom trigger that does not open, toggle, or name the menu, a disabled one that opens, a missing warning, or a wrong Back row name fails. | audit:DropdownMenu/accessibility |
| FR10, AR2, ORD1 | DropdownMenu.test.tsx "DropdownMenuItem href" and "link rows — the browser's own clicks" cases |
Plain, modified, middle, and right click; Enter; bottom sheet; disabled; blocked | A row that is not an anchor, a modified click that runs onClick, a middle click that does not close, a disabled row with an address, or a live blocked destination fails. Evidence gap: no test asserts the order of onClick, close, and navigation. |
audit:DropdownMenu/behavior |
| FR11, AR3 | DropdownMenuSubMenu.test.tsx "drill-in on a phone" cases; DropdownMenuDrillIn.a11y.chromium.spec.ts |
Phone and laptop; forced presentations; theme breakpoint; reset on close | A flyout on a phone, a drill-in on a laptop by default, a wrong name, a Back that loses focus, or a drilled view that survives a close fails. | audit:DropdownMenu/accessibility |
| FR12, AR4 | DropdownMenu.test.tsx keyboard cases ("ArrowDown on the last row wraps to the first, ArrowUp on the first to the last", "ArrowUp on the trigger opens with the last row highlighted", "PageDown moves to the last row and PageUp back to the first", "the opening key's auto-repeat does not act on the highlighted row"), open-focus cases, typeahead cases, and "has aria-haspopup and aria-expanded attributes" |
Wrap, Page keys, open keys, auto-repeat, typeahead | A missing wrap, a Page key that does not move, an ArrowUp open on the first row, an auto-repeat that acts, or a missing typeahead match fails. Evidence gap: no test asserts PageDown past the visible rows, typeahead ignoring chords or composition, or aria-controls on the Button trigger. |
audit:DropdownMenu/accessibility |
| FR13 | DropdownMenuSubMenu.test.tsx safe-triangle cases |
Diagonal path, pause inside, leaving both | A flyout that closes inside the triangle or stays open after leaving it fails. | audit:DropdownMenu/behavior |
| FR14 | DropdownMenu.test.tsx section cases |
Titled and untitled sections | A missing group role or title fails. | audit:DropdownMenu/accessibility |
| FR15, AR5 | DropdownMenu.test.tsx header and footer cases, including the hidden-control, open-sub-menu, and header radio-group cases; MenuHeaderFooter.a11y.chromium.spec.ts |
Regions present and absent; hidden controls; open flyout; custom trigger; bottom sheet | A region inside the menu, a missing or unnamed dialog, a wrong aria-haspopup, a Tab that leaves the popover, a hidden control taken as a stop, or a region whose keys the menu takes fails. |
audit:DropdownMenu/accessibility |
| FR17, AR6 | DropdownMenu, MoreMenu, ContextMenu and NavHeadingMenu keyboard tests, plus a real-browser keyboard check of focus order and blocked activation and a real-browser accessibility-tree check that a focused disabled row is announced as disabled (spec:AST-085 Platform support); disabled-row cases |
Disabled rows | A disabled row that runs a caller handler, closes the menu, is skipped by the arrow keys or type-ahead, or is not announced as disabled fails. | audit:DropdownMenu/accessibility |
| FR20, AR7 | DropdownMenuSubMenu.test.tsx header and footer cases, including "on a phone"; SubMenuHeaderFooter.a11y.chromium.spec.ts; ContextMenu.test.tsx "shows a sub-menu with a header or footer as its rows alone, and says why in development" |
Fine pointer and phone; Escape paths; nested flyouts; pointer leaving | A region inside a menu, an unnamed dialog, a Tab walk that does not wrap, an Escape that closes the root, or a flyout that closes while focus is inside fails. | audit:DropdownMenu/accessibility |
| FR21 | Evidence gap: no test, matching the FR21 gap | — | — | audit:DropdownMenu/behavior |
| FR22 | DropdownMenu.test.tsx "DropdownMenu entrance under a finger" cases; useMenuPress.test.tsx "an input hold over the menu" cases; DropdownMenuEntranceHold.interaction.browser.spec.ts |
A tap outside and a finger's slide while the menu enters; a mouse click | A tap during the entrance that closes the menu, clicks the page or moves focus, a slide that picks nothing, or a held mouse fails. | audit:DropdownMenu/behavior |
| FR23 | DropdownMenu.test.tsx Tab cases; DropdownMenuSubMenu.test.tsx "Tab from a flyout leaves the whole menu" suite |
top level, one and two levels down, Shift+Tab | A Tab that leaves any level open, a second onOpenChange(false), or a prevented Tab fails. |
audit:DropdownMenu/accessibility |
| PR1 | Evidence gap: no test asserts the listener and observer bounds | — | — | audit:DropdownMenu/behavior |
| Theming anatomy map | scripts/check-knowledge.mjs |
Canonical anatomy and targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | audit:DropdownMenu/theming |
Current-state impact
- Finger press-open (FR8). A held finger opens the menu after a 500 ms
hold, and a tap at its click, instead of as
spec:AST-094FR29 states. - Touch grow and pan dismissal (FR21). Under a finger the menu appears and
leaves with the layer's own entrance and exit instead of growing out of and
back into the Trigger button, and a pan that starts outside does not close
it, against
spec:AST-094FR31 and FR32. - Still mouse after a finger (FR22). Known gap: after a finger, a still mouse's first press does nothing unless the mouse rests where the page last heard it when the entering menu's shield came up.
- Delegated Trigger Button gaps (FR3). The Trigger button scales on a press
under reduced motion and holds a fixed height, as
component:Buttonrecords, againstdesign:reduced-motionDR1 andspec:AST-102FR4. - Rich sheet heading for caller-rendered triggers (OQ2). With
renderTrigger, the bottom-sheet heading shows only the flattened text of the trigger's accessible name, and a trigger with no name gets no heading. - Deferred show. When the menu's show waits for another popover operation, its opening release off the trigger closes it, against FR8.
Decision log
DEC-1 — Pointer dismissal returns focus to the trigger, ring suppressed
Reference: component:DropdownMenu/DEC-1
Decider: cixzhang, 2026-10-02
Blurring the trigger after a pointer dismissal would keep Safari from painting
a ring after a touch pick, but focus falling to the page loses a keyboard user
who reaches for the arrows next. Focus returns to the trigger and the shared focus-return visibility helper suppresses the ring
after pointer input (architecture:interaction-modality INV1), as the
bottom-sheet presentation already did. The press model's own decisions remain
in module:DropdownMenu/useMenuPress.
DEC-2 — menuMaxHeight is a number of pixels
Reference: component:DropdownMenu/DEC-2
Decider: cixzhang, 2026-10-02
menuMaxHeight replaces only the 300px term of the cap; the viewport gutters
still bound the menu, so a menu that must show all of its rows (a docked phone
menu of eleven 44px rows) can, without ever overflowing the screen. The dynamic
value uses 100dvb alone; every browser with anchor positioning has it.
A prop rather than a theme variable, because the need is situational — one menu with many rows — rather than a product-wide preference, and a prop reads more clearly at the callsite that has the problem.
The value is a number of pixels. Rejected: an arbitrary CSS length (50vh,
calc(...)), which is product-shaped tuning on a shared component that
spec:AST-002 does not admit, and which lets a caller write a cap the
viewport term cannot reason about.
DEC-3 — Any control can open a menu
Reference: component:DropdownMenu/DEC-3
Decider: cixzhang, 2026-10-02
renderTrigger is a render prop handing the caller DropdownMenuTriggerProps
to spread, so the press model, the keyboard opens and the ARIA wiring ride the
same code path as the built-in Button, and the menu is named by the control
through aria-labelledby. button and renderTrigger are mutually exclusive
(a dev warning); the Button path is unchanged.
The prop is named for spec:AST-055 DEC-5 and DEC-6: render<X> is the
prefix for every render prop in the system, and a bare trigger is already
public with a different shape on Collapsible, where it is a ReactNode
slot, so one word would otherwise mean two things.
Rejected: a content slot taking a rendered element. A slot cannot hand the caller the props the control must carry, so the component would have to reach into the element to attach them.
The open state reaches the caller's control as aria-expanded on the spread
props, and the prop's documentation shows styling from that attribute. A
pressed look keyed to :active is not a substitute: :active does not
behave the same under a coarse pointer, which is why menu rows drop
coarse-pointer :active paint entirely.
Rejected: an as prop on the Button — an icon button, a chip, an avatar and a
list row are not Button variants; a slot component — hides which props must
reach the control.
DEC-4 — Sub-menus drill in on a phone
Reference: component:DropdownMenu/DEC-4
Decider: cixzhang, 2026-10-02
A flyout beside a phone-width menu has no room. When a compact touch display
opened the menu — sampled once, as it opens, so the menu never changes shape
under a pointer — a sub-menu row pushes its view onto a stack the root keeps
(useMenuDrillIn, internal) and the root shows that view in place of its rows:
a "Back to " row, then the sub-menu's rows, inside the same menu box.
The sub-menu portals its list into the root's host so the row stays mounted,
its rows stay live, and Back has something to return focus to; sibling rows
and dividers need no knowledge of it. Works in compound and data mode and in
ContextMenu; presentation overrides the policy.
The query is COMPACT_TOUCH_PRESENTATION_QUERY, the one the root
presentation already uses to decide its bottom sheet, so one component
carries one meaning of "adaptive". A bare (pointer: coarse) disagreed with
it on a large touch tablet: the menu stayed an anchored popover while its
sub-menus replaced rows in place, a combination nobody designed.
The public surface is presentation alone. useMenuDrillIn and its
DropdownMenuDrillIn view-stack controller stay internal: exporting them
would make internal machinery permanent API that nothing here requires a
caller to touch. A product that later needs to drive the stack earns a
deliberate component or hook then, with its own contract.
Rejected: a flipped flyout — lands over the parent rows and reads as a second
menu; drill-in in data mode only — every menu in the app is compound; a
{label, children} snapshot pushed onto the stack — unmounts the row and
breaks focus return.
DEC-6 — A titled group of rows is DropdownMenuGroup
Reference: component:DropdownMenu/DEC-6
Decider: cixzhang, 2026-10-03
Data mode could title a run of rows through {type: 'section', title} and
compound mode could not, so the menus that most need grouping — checkbox
rows, radio groups, rows mounted conditionally, all of which must be
compound — left a screen reader a run of loose rows where a sighted user saw
two clusters. The compound peer names its rows through aria-labelledby on
the visible heading and reuses the dropdown-menu-section-heading treatment,
so one heading looks and reads the same in both modes.
The component is named for the role="group" it renders. The data model
keeps DropdownMenuSection for its {type: 'section'} entry: the two words
describe the same concept, and one name across both would collide with that
exported type. Rejected: renaming the component to DropdownMenuSection,
which collides; renaming both, which breaks a public type for a wording
change.
title is ReactNode. A rich heading is a legitimate need, and the data
mode's string title is the narrower case rather than the model to match. A
focusable node inside a heading lands in the group but outside the roving
focus order, so the arrow keys cannot reach it; the type does not prevent
that and a case pins the behavior instead.
DEC-8 — Controls beside the rows go in header and footer
Reference: component:DropdownMenu/DEC-8
Decider: cixzhang, 2026-10-11
role="menu" admits only menu items, groups and separators. A filter field
or a "Create" button placed among the rows makes the menu invalid to a screen
reader, and makes the menu's key handling and press model fight the control.
The control belongs beside the menu, not in it. header and footer place it
there: in the same popover or sheet, outside the menu element. Outside the
menu element, the menu never claims the control's keys or presses. Because
children stay rows only, nothing can be placed between rows; the component
needs no inspection of its children to keep that true.
The menu becomes one Tab stop between the regions, so the popover reads as one Tab sequence: header, menu, footer, inside the dialog of DEC-10. Focus on open is unchanged. Rejected: letting the menu's handlers step aside for controls placed among the rows — that makes invalid structure work instead of fixing it; and a caller-wrapped items element, which leaves "nothing between the rows" to convention.
DEC-9 — The trigger is a Menu Button, arrow-key opening included
Reference: component:DropdownMenu/DEC-9
Decider: cixzhang, 2026-10-13
The pointer trigger already plays the Menu Button's role, so it carries the pattern's required parts (AR4). ArrowDown and ArrowUp opening go beyond the adoption rule's required set and stay as a named exception because the component shipped them (FR12 keeps the wrap once the menu is open) and removing a working keyboard path would cost the users who have it. ContextMenu and NavMenu are not covered by this decision.
Rejected: dropping arrow-key opening to match the rule's default; adopting the pattern for every control that opens any layer.
DEC-10 — A popover with a header or footer is a modal dialog, and Tab wraps
Reference: component:DropdownMenu/DEC-10
Decider: cixzhang, 2026-10-13
A popover that holds a menu and controls that are not menu items is not a
menu: a trigger exposing aria-haspopup="menu" promises a menu, and the
popover then holds a field or a button that is not one. With header or
footer, the popover is therefore exposed as a named modal dialog with the
menu inside it, the trigger says aria-haspopup="dialog", and
aria-controls names the popover that holds the dialog. Moving the
menu role inward keeps every row a menu item and every other control outside
the menu. Tab and Shift+Tab wrap within the dialog, as the APG Dialog
pattern requires; Escape and a press outside close it. Without either prop
the component is unchanged: a Menu Button whose Tab closes the menu. Rejected:
closing on Tab past either end, which leaves a modal dialog by Tab.
DEC-11 — A disabled menu row is reached by the keyboard and stays inert
Reference: component:DropdownMenu/DEC-11
Decider: cixzhang, owner decision, 2026-11-04
In a menu, a disabled row stays in the keyboard path so a person learns it exists and why it is unavailable, as the WAI-ARIA Menu pattern and its keyboard guidance recommend for disabled menu items. Arrow keys, Home, End and type-ahead visit it; it takes focus and is announced as disabled; it does nothing when activated and does not close the menu. Opening a menu from the keyboard still lands on an enabled row: the first, or the last after ArrowUp on the trigger. The rule covers DropdownMenu, its sub-menus, MoreMenu, ContextMenu and NavHeadingMenu; other menus are out of scope for this decision. Other composites, such as a toolbar, a button group or a listbox, keep their own navigation. Rejected: skipping disabled rows, which hides an unavailable action and its reason from keyboard and screen-reader users.
Open questions
- OQ2 — Rich sheet heading for caller-rendered triggers. (
human-api) WithrenderTrigger, the bottom-sheet heading and the dialog's name come from the trigger's accessible name read from the page, so a rich trigger (an avatar and a name, an icon and a label) shows only flattened text in the sheet heading, and a trigger with no name gets no heading. Open: whether DropdownMenu takes an explicit heading (a node), reuses the trigger's rendered content, or keeps the plain-text name; and whether that name should come from an explicit source rather than a read from the page.
Content boundary
This file does not duplicate consumer prop tables, item examples, focus and positioning algorithms, implementation steps, or shared modality, layer, dismissal, and theming rules. It links to their owners.