Skip to content

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

TypeScript

fix(core): add menu placement options (#2770)

Cindy Zhang2914aabc0075
diff --git a/apps/storybook/stories/DropdownMenu.stories.tsx b/apps/storybook/stories/DropdownMenu.stories.tsx
index 2f8761766d..a95b271ee5 100644
--- a/apps/storybook/stories/DropdownMenu.stories.tsx
+++ b/apps/storybook/stories/DropdownMenu.stories.tsx
@@ -40,6 +40,11 @@ const meta: Meta<typeof XDSDropdownMenu> = {
control: 'text',
description: 'Custom menu width (number for px or CSS string)',
},
+ placement: {
+ control: 'select',
+ options: ['above', 'below', 'start', 'end'],
+ description: 'Menu placement relative to trigger',
+ },
'data-testid': {
control: 'text',
description: 'Test ID for testing frameworks',
@@ -496,3 +501,17 @@ export const CompoundWithDescriptions: Story = {
</XDSDropdownMenu>
),
};
+
+export const PlacementAbove: Story = {
+ render: () => (
+ <XDSDropdownMenu
+ button={{label: 'Bottom toolbar menu'}}
+ placement="above"
+ items={[
+ {label: 'Edit', onClick: () => console.log('Edit')},
+ {label: 'Duplicate', onClick: () => console.log('Duplicate')},
+ {label: 'Delete', onClick: () => console.log('Delete')},
+ ]}
+ />
+ ),
+};
diff --git a/apps/storybook/stories/Selector.stories.tsx b/apps/storybook/stories/Selector.stories.tsx
index 6a1dc02278..1f573e3e78 100644
--- a/apps/storybook/stories/Selector.stories.tsx
+++ b/apps/storybook/stories/Selector.stories.tsx
@@ -50,6 +50,12 @@ const meta: Meta<typeof XDSSelector> = {
options: ['sm', 'md', 'lg'],
description: 'Size variant of the selector',
},
+ placement: {
+ control: 'select',
+ options: ['above', 'below', 'start', 'end'],
+ description:
+ 'Explicit menu placement. Leave unset for selected-item overlay behavior.',
+ },
isDisabled: {
control: 'boolean',
description: 'Whether the selector is disabled',
@@ -554,3 +560,26 @@ export const ClearableWithStatus: Story = {
status: {type: 'warning', message: 'Selection is recommended'},
},
};
+
+export const PlacementAbove: Story = {
+ render: args => {
+ const {
+ value: argsValue,
+ onChange: _onChange,
+ changeAction: _changeAction,
+ hasClear: _hc,
+ ...rest
+ } = args;
+ const [value, setValue] = useState(argsValue ?? 'Banana');
+ return (
+ <XDSSelector
+ {...rest}
+ label="Bottom toolbar selector"
+ options={['Apple', 'Banana', 'Cherry', 'Date']}
+ value={value}
+ onChange={v => setValue(v)}
+ placement="above"
+ />
+ );
+ },
+};
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index 194bfb31e8..9514e82831 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -59,6 +59,13 @@ export const docs = {
description:
'Custom menu width; defaults to matching the trigger button width.',
},
+ {
+ name: 'placement',
+ type: "'above' | 'below' | 'start' | 'end'",
+ description:
+ 'Menu placement relative to the trigger. Defaults below; the layer automatically flips when there is not enough viewport space.',
+ default: "'below'",
+ },
{
name: 'onClick',
type: '() => void',
@@ -184,6 +191,13 @@ export const docsZh = {
description:
'自定义菜单宽度;默认与触发按钮同宽。',
},
+ {
+ name: 'placement',
+ type: "'above' | 'below' | 'start' | 'end'",
+ description:
+ '菜单相对于触发器的位置。默认在下方;当视口空间不足时图层会自动翻转。',
+ default: "'below'",
+ },
{
name: 'onClick',
type: '() => void',
@@ -278,6 +292,7 @@ export const docsDense = {
isMenuOpen: 'controlled open state',
onOpenChange: 'callback on open state change',
menuWidth: 'custom menu width; default matches trigger button',
+ placement: 'menu placement relative to trigger; default below with viewport auto-flip',
onClick: 'trigger button click callback',
hasChevron: 'show chevron on trigger; false for icon-only triggers',
hasAutoFocus: 'auto-focus first item on open; false for showcases',
diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx
index 94bae0d7c3..b2eb76df84 100644
--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx
+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx
@@ -63,6 +63,37 @@ describe('XDSDropdownMenu', () => {
expect(screen.getByRole('menu', {hidden: true})).toBeInTheDocument();
});
+ it('defaults menu placement below', () => {
+ render(
+ <XDSDropdownMenu
+ button={{label: 'Actions'}}
+ items={[{label: 'Item 1'}]}
+ />,
+ );
+ const popover = screen
+ .getByRole('menu', {hidden: true})
+ .closest('[popover]');
+ expect(popover?.getAttribute('style')).toContain(
+ 'position-area: bottom span-right',
+ );
+ });
+
+ it('supports explicit menu placement', () => {
+ render(
+ <XDSDropdownMenu
+ button={{label: 'Actions'}}
+ placement="above"
+ items={[{label: 'Item 1'}]}
+ />,
+ );
+ const popover = screen
+ .getByRole('menu', {hidden: true})
+ .closest('[popover]');
+ expect(popover?.getAttribute('style')).toContain(
+ 'position-area: top span-right',
+ );
+ });
+
it('has aria-haspopup and aria-expanded attributes', () => {
render(
<XDSDropdownMenu
diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx
index f9591bea5d..48aa04e1bd 100644
--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx
+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx
@@ -44,9 +44,9 @@ import {
} from './XDSDropdownMenuContext';
import {useListFocus} from '../hooks/useListFocus';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
+import type {LayerPlacement} from '../Layer/useXDSLayer';
import {
spacingVars,
- sizeVars,
radiusVars,
durationVars,
easeVars,
@@ -74,32 +74,19 @@ const styles = stylex.create({
popover: {
minWidth: 'anchor-size(width)',
},
- popoverGap: {
+ popoverBlockGap: {
marginBlockStart: spacingVars['--spacing-1'],
marginBlockEnd: spacingVars['--spacing-1'],
},
+ popoverInlineGap: {
+ marginInlineStart: spacingVars['--spacing-1'],
+ marginInlineEnd: spacingVars['--spacing-1'],
+ },
popoverCustomWidth: (width: string | number) => ({
minWidth: typeof width === 'number' ? `${width}px` : width,
}),
});
-/**
- * Overlay offset styles: shift the popover up so the first item's text
- * aligns with the trigger button's text.
- * Formula: -(container_padding + trigger_height)
- */
-const popoverOverlayStyles = stylex.create({
- sm: {
- marginBlockStart: `calc(-1 * (${spacingVars['--spacing-1']} + ${sizeVars['--size-element-sm']}))`,
- },
- md: {
- marginBlockStart: `calc(-1 * (${spacingVars['--spacing-1']} + ${sizeVars['--size-element-md']}))`,
- },
- lg: {
- marginBlockStart: `calc(-1 * (${spacingVars['--spacing-1']} + ${sizeVars['--size-element-lg']}))`,
- },
-});
-
// =============================================================================
// Types
// =============================================================================
@@ -139,6 +126,13 @@ interface XDSDropdownMenuBaseProps extends XDSBaseProps {
menuWidth?: number | string;
onClick?: () => void;
hasChevron?: boolean;
+ /**
+ * Position placement relative to the trigger.
+ * Uses the same placement values as other XDS layer-based components.
+ * @default 'below'
+ */
+ placement?: LayerPlacement;
+
/**
* Whether to auto-focus the first menu item when the menu opens.
* Set to `false` for inline showcases or documentation previews
@@ -196,6 +190,7 @@ export function XDSDropdownMenu({
menuWidth,
onClick,
hasChevron = true,
+ placement = 'below',
hasAutoFocus = true,
className,
style,
@@ -357,6 +352,10 @@ export function XDSDropdownMenu({
const popoverXstyle = menuWidth
? styles.popoverCustomWidth(menuWidth)
: styles.popover;
+ const popoverGapStyle =
+ placement === 'above' || placement === 'below'
+ ? styles.popoverBlockGap
+ : styles.popoverInlineGap;
// Context for compound items
const contextValue = useMemo<XDSDropdownMenuContextValue>(
@@ -411,13 +410,9 @@ export function XDSDropdownMenu({
</XDSDropdownMenuContext>
</div>,
{
- placement: 'below',
+ placement,
alignment: 'start',
- xstyle: [
- popoverXstyle,
- popoverOverlayStyles[menuSize],
- layerAnimations.below,
- ],
+ xstyle: [popoverXstyle, popoverGapStyle, layerAnimations[placement]],
},
)}
</>
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index 5f55f032c8..fed560f769 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -62,6 +62,12 @@ export const docs = {
description: 'Placeholder text for the search input.',
default: "'Search...'",
},
+ {
+ name: 'placement',
+ type: "'above' | 'below' | 'start' | 'end'",
+ description:
+ 'Dropdown placement relative to the trigger. Omit for the default selector behavior: align the selected item over the trigger and clamp the menu to the viewport. Set a value to use explicit layer positioning.',
+ },
{
name: 'placeholder',
type: 'string',
@@ -224,6 +230,12 @@ export const docsZh = {
description: '搜索输入的占位文本。',
default: "'Search...'",
},
+ {
+ name: 'placement',
+ type: "'above' | 'below' | 'start' | 'end'",
+ description:
+ '下拉层相对于触发器的位置。省略时使用选择器默认行为:将已选项对齐到触发器上并限制在视口内。设置后使用显式图层定位。',
+ },
{
name: 'placeholder',
type: 'string',
@@ -366,6 +378,7 @@ export const docsDense = {
hasClear: 'Shows clear button when value selected. onChange also accepts null on clear.',
hasSearch: 'Shows search input for filtering options.',
searchPlaceholder: 'Placeholder text for search input.',
+ placement: 'Dropdown placement. Omit for selected-item overlay clamped to viewport; set value for explicit layer positioning.',
placeholder: 'Placeholder text when no value selected.',
size: 'Size variant for selector.',
isDisabled: 'Disables selector.',
diff --git a/packages/core/src/Selector/XDSSelector.test.tsx b/packages/core/src/Selector/XDSSelector.test.tsx
index f4c7c49939..bfbdc2b84e 100644
--- a/packages/core/src/Selector/XDSSelector.test.tsx
+++ b/packages/core/src/Selector/XDSSelector.test.tsx
@@ -10,7 +10,7 @@
*/
import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {XDSSelector} from './XDSSelector';
@@ -46,6 +46,65 @@ const h = {hidden: true} as const;
const OPTIONS = ['Apple', 'Banana', 'Cherry'];
+function rect({
+ top,
+ bottom,
+ left = 0,
+ right = 100,
+ width = right - left,
+ height = bottom - top,
+}: {
+ top: number;
+ bottom: number;
+ left?: number;
+ right?: number;
+ width?: number;
+ height?: number;
+}): DOMRect {
+ return {
+ x: left,
+ y: top,
+ top,
+ bottom,
+ left,
+ right,
+ width,
+ height,
+ toJSON: () => ({}),
+ };
+}
+
+function mockSelectorRects() {
+ const originalGetBoundingClientRect =
+ HTMLElement.prototype.getBoundingClientRect;
+ const originalInnerHeight = Object.getOwnPropertyDescriptor(
+ window,
+ 'innerHeight',
+ );
+ HTMLElement.prototype.getBoundingClientRect = function () {
+ if (this.getAttribute('role') === 'combobox') {
+ return rect({top: 160, bottom: 190, height: 30});
+ }
+ if (this.getAttribute('role') === 'listbox') {
+ return rect({top: 190, bottom: 310, height: 120});
+ }
+ if (this.id.endsWith('-item-1')) {
+ return rect({top: 220, bottom: 250, height: 30});
+ }
+ return originalGetBoundingClientRect.call(this);
+ };
+ Object.defineProperty(window, 'innerHeight', {
+ value: 200,
+ configurable: true,
+ });
+ return () => {
+ HTMLElement.prototype.getBoundingClientRect = originalGetBoundingClientRect;
+ if (originalInnerHeight) {
+ Object.defineProperty(window, 'innerHeight', originalInnerHeight);
+ }
+ };
+}
+
describe('XDSSelector', () => {
it('renders with placeholder when no value', () => {
render(
@@ -66,6 +125,79 @@ describe('XDSSelector', () => {
expect(screen.getByRole('combobox')).toHaveTextContent('Banana');
});
+ it('supports explicit menu placement', () => {
+ render(
+ <XDSSelector
+ label="Fruit"
+ options={OPTIONS}
+ value="Banana"
+ onChange={() => {}}
+ placement="above"
+ />,
+ );
+ const popover = screen
+ .getByRole('listbox', {hidden: true})
+ .closest('[popover]');
+ expect(popover?.getAttribute('style')).toContain(
+ 'position-area: top span-right',
+ );
+ });
+
+ it('clamps the default selected-item overlay to the viewport', async () => {
+ const restoreRects = mockSelectorRects();
+ const user = userEvent.setup();
+ try {
+ render(
+ <XDSSelector
+ label="Fruit"
+ options={OPTIONS}
+ value="Banana"
+ onChange={() => {}}
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const popover = screen
+ .getByRole('listbox', {hidden: true})
+ .closest('[popover]');
+ await waitFor(() => {
+ expect(popover?.getAttribute('style')).toContain(
+ 'margin-block-start: -110px',
+ );
+ });
+ } finally {
+ restoreRects();
+ }
+ });
+
+ it('does not apply selected-item overlay offset when placement is explicit', async () => {
+ const restoreRects = mockSelectorRects();
+ const user = userEvent.setup();
+ try {
+ render(
+ <XDSSelector
+ label="Fruit"
+ options={OPTIONS}
+ value="Banana"
+ onChange={() => {}}
+ placement="above"
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const popover = screen
+ .getByRole('listbox', {hidden: true})
+ .closest('[popover]');
+ await waitFor(() => {
+ expect(popover?.getAttribute('style')).not.toContain(
+ 'margin-block-start',
+ );
+ });
+ } finally {
+ restoreRects();
+ }
+ });
+
describe('hasClear', () => {
it('shows selected value label when hasClear is enabled', () => {
render(
diff --git a/packages/core/src/Selector/XDSSelector.tsx b/packages/core/src/Selector/XDSSelector.tsx
index 4d0b8b3015..3444f42a29 100644
--- a/packages/core/src/Selector/XDSSelector.tsx
+++ b/packages/core/src/Selector/XDSSelector.tsx
@@ -37,6 +37,7 @@ import {
} from '../Field';
import {XDSDivider} from '../Divider';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
+import type {LayerPlacement} from '../Layer/useXDSLayer';
import {XDSSpinner} from '../Spinner';
import {
colorVars,
@@ -175,9 +176,6 @@ const styles = stylex.create({
opacity: 0,
transition: 'none',
},
- dropdownOffset: (offset: number) => ({
- marginTop: offset,
- }),
// Popover container (for anchor positioning)
popover: {
@@ -433,6 +431,16 @@ interface XDSSelectorPropsBase<
*/
searchPlaceholder?: string;
+ /**
+ * Position placement relative to the trigger.
+ *
+ * Omit to use the selector's default selected-item overlay behavior: the
+ * selected item is positioned over the trigger and clamped to the viewport.
+ * Set a placement to opt into explicit layer positioning (for example,
+ * `placement="above"` for bottom-fixed toolbars).
+ */
+ placement?: LayerPlacement;
+
/**
* Whether the dropdown starts open on mount.
* Useful for showcases and previews.
@@ -527,6 +535,7 @@ export function XDSSelector<T extends XDSSelectorOptionType>(
children,
hasSearch = false,
searchPlaceholder = 'Search...',
+ placement,
isDefaultOpen = false,
'data-testid': testId,
xstyle,
@@ -615,19 +624,26 @@ export function XDSSelector<T extends XDSSelectorOptionType>(
// eslint-disable-next-line @eslint-react/exhaustive-deps -- mount-only: isDefaultOpen is not reactive
}, []);
- // Calculate offset to position selected item over trigger
+ // Calculate offset to position selected item over trigger. Explicit
+ // placement opts out of the selector-specific overlay behavior and uses the
+ // standard layer positioning API instead.
+ const shouldOverlaySelectedItem = placement == null && !hasSearch;
const {offset: rawOffset, isPositioned: rawIsPositioned} =
useSelectedItemOffset({
- isOpen: popover.isOpen,
+ isOpen: popover.isOpen && shouldOverlaySelectedItem,
selectedItemIndex,
listboxId,
listboxRef,
triggerRef,
});
- // Disable macOS overlay positioning when search is active
- const selectedItemOffset = hasSearch ? 0 : rawOffset;
- const isPositioned = hasSearch ? true : rawIsPositioned;
+ const selectedItemOffset = shouldOverlaySelectedItem ? rawOffset : 0;
+ const isPositioned = shouldOverlaySelectedItem ? rawIsPositioned : true;
+ const popoverPlacement = placement ?? 'below';
+ const popoverOffsetStyle: React.CSSProperties | undefined =
+ selectedItemOffset > 0
+ ? {marginBlockStart: `-${selectedItemOffset}px`}
+ : undefined;
// Selector behavior (keyboard nav, typeahead, selection)
const {
@@ -936,15 +952,15 @@ export function XDSSelector<T extends XDSSelectorOptionType>(
{...stylex.props(
styles.dropdown,
!isPositioned && styles.dropdownHidden,
- styles.dropdownOffset(-selectedItemOffset),
)}>
{renderOptions()}
</div>
),
{
- placement: 'below',
+ placement: popoverPlacement,
alignment: 'start',
- xstyle: [styles.popover, layerAnimations.below],
+ xstyle: [styles.popover, layerAnimations[popoverPlacement]],
+ style: popoverOffsetStyle,
},
)}
</XDSField>
diff --git a/packages/core/src/Selector/hooks.ts b/packages/core/src/Selector/hooks.ts
index 7b7a7faa09..a1a1bc7f9a 100644
--- a/packages/core/src/Selector/hooks.ts
+++ b/packages/core/src/Selector/hooks.ts
@@ -34,11 +34,11 @@ interface UseSelectedItemOffsetResult {
* Calculates the offset needed to position the dropdown so that the selected
* item appears centered over the trigger button (macOS-style selector).
*
- * When the offset would push the popover out of the viewport (e.g. the selector
- * is near the top of the page), the offset is clamped so the popover stays
- * fully visible. If the selected item can't be shown over the trigger without
- * going out of bounds, the popover falls back to appearing below the trigger
- * with no offset.
+ * The desired dropdown top is calculated directly from the trigger center and
+ * selected-item center, then clamped to the viewport. This preserves the
+ * default "selected item over trigger" behavior while letting the menu slide
+ * upward near the bottom edge or downward near the top edge instead of being
+ * clipped off-screen.
*/
export function useSelectedItemOffset({
isOpen,
@@ -83,47 +83,34 @@ export function useSelectedItemOffset({
return;
}
- // Get positions
+ // Get positions. JSDOM returns zero rects by default, but browsers provide
+ // real dimensions before paint via layout effect.
const listboxRect = listboxRef.current.getBoundingClientRect();
const itemRect = targetItem.getBoundingClientRect();
const triggerRect = triggerRef.current.getBoundingClientRect();
- // Calculate offset to center the item over the trigger
- // The listbox is positioned below the trigger by anchor positioning (top of listbox at bottom of trigger)
- // We need to move it UP so the selected item's center aligns with trigger's center
- //
- // Item center relative to listbox top:
- const itemCenterInListbox =
- itemRect.top - listboxRect.top + itemRect.height / 2;
- //
- // To center item over trigger, we need to move up by:
- // (item center in listbox) + (half trigger height to reach trigger's center from its bottom edge)
- const calculatedOffset = itemCenterInListbox + triggerRect.height / 2;
-
- // Clamp to viewport bounds — don't let the popover go above the screen.
- // The popover's top edge after offset = triggerRect.bottom - calculatedOffset.
- // We want: top >= 0 (viewport top) and bottom <= viewportHeight.
- const popoverTopAfterOffset = triggerRect.bottom - calculatedOffset;
const listboxHeight = listboxRect.height;
- const popoverBottomAfterOffset = popoverTopAfterOffset + listboxHeight;
- const viewportHeight = window.innerHeight;
+ if (listboxHeight <= 0) {
+ commitPosition(0, true);
+ return;
+ }
- let clampedOffset = calculatedOffset;
+ // Item center relative to listbox top. This remains stable even as the
+ // popover's top changes between measurements.
+ const itemCenterInListbox =
+ itemRect.top - listboxRect.top + itemRect.height / 2;
+ const triggerCenter = triggerRect.top + triggerRect.height / 2;
- if (popoverTopAfterOffset < 0) {
- // Would go above viewport — reduce offset so top edge sits at viewport top
- clampedOffset = calculatedOffset + popoverTopAfterOffset;
- } else if (popoverBottomAfterOffset > viewportHeight) {
- // Would go below viewport — reduce offset so bottom edge sits at viewport bottom
- clampedOffset =
- calculatedOffset - (popoverBottomAfterOffset - viewportHeight);
- }
+ // Desired top aligns the selected item's center with trigger center.
+ const desiredTop = triggerCenter - itemCenterInListbox;
+ const viewportHeight = window.innerHeight;
+ const maxTop = Math.max(0, viewportHeight - listboxHeight);
+ const clampedTop = Math.min(Math.max(desiredTop, 0), maxTop);
- // If even the clamped offset is negative or near-zero, fall back to
- // showing the popover below the trigger with no overlay offset
- if (clampedOffset < 0) {
- clampedOffset = 0;
- }
+ // useXDSLayer positions the popover below the trigger. Apply a negative
+ // block-start margin to the layer container so the listbox top moves from
+ // triggerRect.bottom to clampedTop.
+ const clampedOffset = Math.max(0, triggerRect.bottom - clampedTop);
commitPosition(clampedOffset, true);
}, [