Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(DropdownMenu): menuMaxHeight lifts the 300px cap for a menu that must fit its rows (#6837)

Christopher Chedeau39f263645312
diff --git a/.changeset/menu-max-height.md b/.changeset/menu-max-height.md
new file mode 100644
index 0000000000..58efb7ab7a
--- /dev/null
+++ b/.changeset/menu-max-height.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] DropdownMenu takes `menuMaxHeight` to lift the 300px cap for a menu that must fit its rows; the viewport still bounds it.
+
+@vjeux
diff --git a/apps/storybook/stories/DropdownMenu.stories.tsx b/apps/storybook/stories/DropdownMenu.stories.tsx
index e9798a8998..99d8d3182c 100644
--- a/apps/storybook/stories/DropdownMenu.stories.tsx
+++ b/apps/storybook/stories/DropdownMenu.stories.tsx
@@ -1270,3 +1270,25 @@ export const SubmenuViewportFit: Story = {
}
},
};
+
+export const TallMenu: Story = {
+ name: 'menuMaxHeight',
+ render: () => (
+ <DropdownMenu
+ button={{label: 'Eleven rows, no scroll'}}
+ menuMaxHeight={560}
+ items={Array.from({length: 11}, (_, i) => ({
+ label: `Row ${i + 1}`,
+ onClick: () => {},
+ }))}
+ />
+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'A menu is capped at 300px and scrolls past it. `menuMaxHeight` lifts the cap for a menu that must show all of its rows; the viewport still bounds it.',
+ },
+ },
+ },
+};
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index 92b78cc8a1..36995840c8 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -214,6 +214,12 @@ export const docs = {
description:
'Minimum width for the popover presentation. Length values may grow for content; intrinsic and CSS-wide keywords select the preferred inline size. Every form is capped to the available viewport space. Defaults to matching the trigger width up to that cap.',
},
+ {
+ name: 'menuMaxHeight',
+ type: 'number',
+ description:
+ 'Maximum height in pixels for the popover presentation, for a menu that must fit its rows. Lifts the default 300px cap; the viewport still bounds it.',
+ },
{
name: 'placement',
type: "'above' | 'below' | 'start' | 'end'",
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.spec.md b/packages/core/src/DropdownMenu/DropdownMenu.spec.md
index 47b0a4c8e2..ac484bfc05 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.spec.md
+++ b/packages/core/src/DropdownMenu/DropdownMenu.spec.md
@@ -9,7 +9,7 @@ superseded_by: null
approved_by: null
approved_at: null
owners: [cixzhang]
-review_triggers: [theming]
+review_triggers: [theming, public-api, layout]
verified_by:
[
packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
@@ -49,7 +49,7 @@ highlight follows the pointer — is contracted by
- Released default preserved: `yes`
- Compatibility class: additive documentation; the press-model behavior
- delta is recorded in `module:DropdownMenu/useMenuPress` (DEC-3)
+ delta is recorded in `module:DropdownMenu/useMenuPress`
- Controlled/uncontrolled behavior: unchanged
- Migration decision: `module:DropdownMenu/useMenuPress/DEC-3`
@@ -80,20 +80,25 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-No new public concept is introduced. Consumer props, item shapes,
-subcomponents, and presentation policy remain documented in
-`DropdownMenu.doc.mjs` and the subcomponent docs.
+Consumer props, item shapes, subcomponents, and presentation policy remain
+documented in `DropdownMenu.doc.mjs` and the subcomponent docs. One
+component-local concept is added by DEC-3; it 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. |
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| FR1 | Every current 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 | Verified current behavior; no new behavior decided |
-| FR2 | The six current 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 remains on its current painted element. | Current source, docs, and tests | Verified current inventory; no target change |
-| 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. | Current source and owner docs | Verified current delegation; no ownership change |
-| FR4 | The same `dropdown-menu` target reaches the alternative Pointer menu surface and Touch menu surface. Pointer action rows retain `dropdown-menu-item`; touch action rows instead use List's `list-item` target. | Current source and tests | Verified modality split; no target change |
-| FR5 | Both menu surfaces carry `data-astryx-menu-press` and follow `module:DropdownMenu/useMenuPress` FR1–FR7: 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. Trigger opening and keyboard navigation are unchanged. | `module:DropdownMenu/useMenuPress`; `DropdownMenu.test.tsx` press model suite | Proposed; verified in jsdom and real Chromium |
-| FR6 | When the pointer menu closes, focus returns to the Trigger button with a visible ring only when the menu was driven by keyboard; a press outside that landed on a focusable control keeps focus there. | `architecture:interaction-modality` INV1; proposed in this change; `DropdownMenu.test.tsx` closing suite | Proposed; verified in jsdom, pending owner review |
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| FR1 | Every current 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 | Verified current behavior; no new behavior decided |
+| FR2 | The six current 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 remains on its current painted element. | Current source, docs, and tests | Verified current inventory; no target change |
+| 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. | Current source and owner docs | Verified current delegation; no ownership change |
+| FR4 | The same `dropdown-menu` target reaches the alternative Pointer menu surface and Touch menu surface. Pointer action rows retain `dropdown-menu-item`; touch action rows instead use List's `list-item` target. | Current source and tests | Verified modality split; no target change |
+| FR5 | Both menu surfaces carry `data-astryx-menu-press` and follow `module:DropdownMenu/useMenuPress` FR1–FR7: 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. Trigger opening and keyboard navigation are unchanged. | `module:DropdownMenu/useMenuPress`; `DropdownMenu.test.tsx` press model suite | Proposed; verified in jsdom and real Chromium |
+| FR6 | When the pointer menu closes, focus returns to the Trigger button with a visible ring only when the menu was driven by keyboard; a press outside that landed on a focusable control keeps focus there. | `architecture:interaction-modality` INV1; proposed in this change; `DropdownMenu.test.tsx` closing suite | Proposed; verified in jsdom, pending owner review |
+| FR7 | `menuMaxHeight` MUST replace 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. | `component:DropdownMenu/DEC-3` | Proposed; verified in jsdom; owner to confirm DEC-3 |
### Allowed variation
@@ -231,15 +236,16 @@ than adding a DropdownMenu-owned heading target.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| FR1, FR4 | `DropdownMenu.test.tsx` pointer, bottom-sheet, adaptive, section, divider, and drill-in suites | Root pointer, nested pointer, root touch, drill-in | Collapsing presentation-specific parts or owners fails structure, target, or role assertions. | `audit:DropdownMenu/anatomy` |
-| FR2 | DropdownMenu target suites, source inspection, and theming target inventories | All six local targets | Removing, renaming, or assigning a current target to the wrong part fails evidence or inventory. | `audit:DropdownMenu/theming` |
-| FR3 | `DropdownMenuSelectable.test.tsx` plus BottomSheet, List, Indicator, Icon, and Divider owner tests | Trigger, touch actions, icons, checkbox, radio | A composed part loses its owner target or is documented as a new local target. | `audit:DropdownMenu/theming` |
-| Layer relationships | `DropdownMenu.test.tsx`, `DropdownMenuSubMenu.test.tsx`, and current layer/dismissal architecture records | Light dismiss, nested flyout, sheet dismissal | Documentation claims a shared owner where current source retains local behavior, or the reverse. | `audit:DropdownMenu/behavior` |
-| FR5 | `DropdownMenu.test.tsx` press model suite; the module record's own map | Finger slide across rows, outside release by mouse and finger, `touch-action`, root marker | A row acting on the press or the stray click, a lost `touch-action`, or a finger release that closes fails. | `audit:DropdownMenu/behavior` |
-| FR6 | `DropdownMenu.test.tsx` dismissal and closing suites | keyboard dismissal, pointer dismissal, press outside on a control, pointer pick, closed menu | Focus left on the body after a pointer pick, or a ring after pointer input, fails. | `audit:DropdownMenu/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:DropdownMenu/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| FR1, FR4 | `DropdownMenu.test.tsx` pointer, bottom-sheet, adaptive, section, divider, and drill-in suites | Root pointer, nested pointer, root touch, drill-in | Collapsing presentation-specific parts or owners fails structure, target, or role assertions. | `audit:DropdownMenu/anatomy` |
+| FR2 | DropdownMenu target suites, source inspection, and theming target inventories | All six local targets | Removing, renaming, or assigning a current target to the wrong part fails evidence or inventory. | `audit:DropdownMenu/theming` |
+| FR3 | `DropdownMenuSelectable.test.tsx` plus BottomSheet, List, Indicator, Icon, and Divider owner tests | Trigger, touch actions, icons, checkbox, radio | A composed part loses its owner target or is documented as a new local target. | `audit:DropdownMenu/theming` |
+| Layer relationships | `DropdownMenu.test.tsx`, `DropdownMenuSubMenu.test.tsx`, and current layer/dismissal architecture records | Light dismiss, nested flyout, sheet dismissal | Documentation claims a shared owner where current source retains local behavior, or the reverse. | `audit:DropdownMenu/behavior` |
+| FR5 | `DropdownMenu.test.tsx` press model suite; the module record's own map | Finger slide across rows, outside release by mouse and finger, `touch-action`, root marker | A row acting on the press or the stray click, a lost `touch-action`, or a finger release that closes fails. | `audit:DropdownMenu/behavior` |
+| FR6 | `DropdownMenu.test.tsx` dismissal and closing suites | keyboard dismissal, pointer dismissal, press outside on a control, pointer pick, closed menu | Focus left on the body after a pointer pick, or a ring after pointer input, fails. | `audit:DropdownMenu/behavior` |
+| FR7 | `menuMaxHeight` MUST replace 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. | `component:DropdownMenu/DEC-3` | Proposed; verified in jsdom; owner to confirm DEC-3 |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:DropdownMenu/theming` |
## Decision log
@@ -256,6 +262,25 @@ 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.
+
## Open questions
None.
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
index 01c9b3f1ab..f3279215a2 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
@@ -2356,6 +2356,41 @@ describe('DropdownMenu press model', () => {
});
});
+describe('DropdownMenu menuMaxHeight', () => {
+ it('a menu taller than the cap keeps the height it is given', () => {
+ render(
+ <DropdownMenu
+ button={{label: 'Actions'}}
+ menuMaxHeight={528}
+ items={Array.from({length: 12}, (_, i) => ({label: `Row ${i + 1}`}))}
+ />,
+ );
+ const menu = screen.getByRole('menu', {hidden: true});
+ // The cap is lifted to the given height, still bounded by the viewport.
+ expect(menu).toHaveStyle({maxHeight: 'var(--x-maxHeight)'});
+ expect(menu.getAttribute('style')).toContain('min(528px, calc(100dvb');
+ expect(menu.getAttribute('style')).not.toContain('min(300px');
+ // The popover viewport that holds the menu lifts its cap with it.
+ const popover = menu.closest('[popover]');
+ expect(popover?.getAttribute('style')).toContain('min(528px, calc(100dvb');
+ });
+
+ it('keeps the viewport bound below the raised cap', () => {
+ // The cap is the smaller of the two terms, so a tall menu on a short
+ // screen is still bounded by the viewport rather than by the number the
+ // caller asked for.
+ render(
+ <DropdownMenu
+ button={{label: 'Actions'}}
+ menuMaxHeight={720}
+ items={[{label: 'Row'}]}
+ />,
+ );
+ const menu = screen.getByRole('menu', {hidden: true});
+ expect(menu.getAttribute('style')).toContain('min(720px, calc(100dvb');
+ });
+});
+
describe('DropdownMenu focus return after a pointer pick', () => {
function renderMenu(onPick: (label: string) => void = () => {}) {
render(
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenu.tsx
index d418082e10..e21dc4d864 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.tsx
@@ -206,6 +206,19 @@ const styles = stylex.create({
}),
});
+const MENU_VIEWPORT_BLOCK_GUTTERS = `max(${MENU_VIEWPORT_GUTTER}, env(safe-area-inset-top, 0px)) - max(${MENU_VIEWPORT_GUTTER}, env(safe-area-inset-bottom, 0px))`;
+
+// `menuMaxHeight` lifts the 300px cap for a menu that must fit its rows; the
+// viewport still bounds it.
+const dynamicStyles = stylex.create({
+ menuMaxHeight: (maxHeight: string) => ({
+ maxHeight: `min(${maxHeight}, calc(100dvb - ${MENU_VIEWPORT_BLOCK_GUTTERS}))`,
+ }),
+ popoverViewportMaxBlockSize: (maxHeight: string) => ({
+ maxBlockSize: `min(${maxHeight}, calc(100dvb - ${MENU_VIEWPORT_BLOCK_GUTTERS}))`,
+ }),
+});
+
const bottomSheetStyles = stylex.create({
content: {
width: '100%',
@@ -304,6 +317,12 @@ interface DropdownMenuBaseProps extends BaseProps {
* Defaults to the trigger width.
*/
menuWidth?: number | string;
+ /**
+ * Maximum menu height in pixels, for a menu that must fit its rows. Lifts
+ * the default 300px cap; the viewport still bounds it. Ignored by
+ * bottom-sheet presentation.
+ */
+ menuMaxHeight?: number;
onClick?: () => void;
hasChevron?: boolean;
/**
@@ -385,6 +404,7 @@ function DropdownMenuBottomSheet({
items,
presentation: _presentation,
menuWidth: _menuWidth,
+ menuMaxHeight: _menuMaxHeight,
placement: _placement,
alignment: _alignment,
className,
@@ -584,6 +604,7 @@ function DropdownMenuPopover({
isMenuOpen: controlledIsOpen,
onOpenChange,
menuWidth,
+ menuMaxHeight,
onClick,
hasChevron = true,
placement = 'below',
@@ -941,6 +962,7 @@ function DropdownMenuPopover({
? styles.popoverCentered
: styles.popoverAligned;
const isSidePlacement = placement === 'start' || placement === 'end';
+ const resolvedMaxHeight = menuMaxHeight == null ? null : `${menuMaxHeight}px`;
// Context for compound items
const contextValue = useMemo<DropdownMenuContextValue>(
() => ({closeMenu, menuSize}),
@@ -1012,6 +1034,8 @@ function DropdownMenuPopover({
themeProps('dropdown-menu'),
stylex.props(
styles.dropdown,
+ resolvedMaxHeight != null &&
+ dynamicStyles.menuMaxHeight(resolvedMaxHeight),
hasOverflow ? styles.touchPanY : styles.touchNone,
hasOverflow && styles.scrollable,
xstyle,
@@ -1029,6 +1053,8 @@ function DropdownMenuPopover({
offset: spacingVars['--spacing-1'],
xstyle: [
styles.popoverViewport,
+ resolvedMaxHeight != null &&
+ dynamicStyles.popoverViewportMaxBlockSize(resolvedMaxHeight),
alignment === 'center'
? isSidePlacement
? styles.popoverViewportBlockCentered