Skip to content

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

TypeScript

fix(popover): stop announcing listbox/menu popups as modal dialogs (#3350)

Cindy Zhanga478a3dcf46e
diff --git a/.changeset/popover-role-modality.md b/.changeset/popover-role-modality.md
new file mode 100644
index 0000000000..43ebaa8398
--- /dev/null
+++ b/.changeset/popover-role-modality.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] usePopover: add a `role` (`'dialog' | 'none'`) and `isModal` option so listbox and menu popups no longer announce a false modal dialog. Selector, MultiSelector, BaseTypeahead, PowerSearch, DropdownMenu, TabMenu, and the Chat mention menu now expose their own `listbox`/`menu` role instead of being wrapped in `role="dialog" aria-modal="true"` while focus stays on the trigger. Genuine dialog popovers are unchanged (#3343).
+@cixzhang
diff --git a/packages/core/src/Chat/useTriggerMenu.tsx b/packages/core/src/Chat/useTriggerMenu.tsx
index d9d0427712..b1733078b3 100644
--- a/packages/core/src/Chat/useTriggerMenu.tsx
+++ b/packages/core/src/Chat/useTriggerMenu.tsx
@@ -296,6 +296,9 @@ export function useTriggerMenu(
hasLightDismiss: true,
hasCloseButton: false,
hasAutoFocus: false,
+ // The popup's own role="listbox" is the exposed semantics; focus stays in
+ // the contenteditable composer, so a modal dialog wrapper is incorrect.
+ role: 'none',
});
// Cleanup on unmount
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
index 266b5e37f6..8093964182 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx
@@ -63,6 +63,22 @@ describe('DropdownMenu', () => {
expect(screen.getByRole('menu', {hidden: true})).toBeInTheDocument();
});
+ it('does not wrap the menu in a role="dialog" aria-modal element', () => {
+ render(
+ <DropdownMenu
+ button={{label: 'Actions'}}
+ items={[{label: 'Item 1'}]}
+ />,
+ );
+ // The popup exposes its own role="menu"; it must not be nested inside a
+ // modal dialog, which would announce an unnamed dialog around the menu
+ // while focus stays on the trigger.
+ expect(screen.queryByRole('dialog', {hidden: true})).not.toBeInTheDocument();
+ expect(
+ document.querySelector('[aria-modal="true"]'),
+ ).not.toBeInTheDocument();
+ });
+
it('defaults menu placement below', () => {
render(
<DropdownMenu
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenu.tsx
index 7e8d3ec69e..d26eb8c080 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.tsx
@@ -249,6 +249,9 @@ export function DropdownMenu({
hasLightDismiss: true,
hasCloseButton: false,
hasAutoFocus: false,
+ // The popup's own role="menu" is the exposed semantics; wrapping it in a
+ // modal dialog would announce an unnamed dialog around the menu.
+ role: 'none',
});
const closeMenu = useCallback(() => {
diff --git a/packages/core/src/MultiSelector/MultiSelector.tsx b/packages/core/src/MultiSelector/MultiSelector.tsx
index 0929862acf..31b3ec0c20 100644
--- a/packages/core/src/MultiSelector/MultiSelector.tsx
+++ b/packages/core/src/MultiSelector/MultiSelector.tsx
@@ -696,7 +696,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
onHide: handleLayerHide,
hasCloseButton: false,
hasAutoFocus: false,
- dialogLabel: `${label} options`,
+ // The popup's own role="listbox" is the exposed semantics; the trigger
+ // keeps DOM focus, so wrapping it in a modal dialog would misrepresent it.
+ role: 'none',
});
// Open dropdown on mount when isDefaultOpen is true
diff --git a/packages/core/src/Popover/usePopover.doc.mjs b/packages/core/src/Popover/usePopover.doc.mjs
index 50fc57fa48..684f7d01c3 100644
--- a/packages/core/src/Popover/usePopover.doc.mjs
+++ b/packages/core/src/Popover/usePopover.doc.mjs
@@ -14,7 +14,9 @@ export const docs = {
{name: 'hasAutoFocus', type: 'boolean', description: 'Whether to automatically focus the first focusable element when opened.', default: 'true'},
{name: 'hasCloseButton', type: 'boolean', description: 'Whether to include a hidden close button that appears for keyboard users.', default: 'true'},
{name: 'closeButtonLabel', type: 'string', description: 'Accessible label for the hidden close button.', default: "'Close popover'"},
- {name: 'dialogLabel', type: 'string', description: 'Accessible label for the popover dialog. Provide one when there is no visible title.'},
+ {name: 'dialogLabel', type: 'string', description: 'Accessible label for the popover dialog (only applies when role is "dialog"). Provide one when there is no visible title.'},
+ {name: 'role', type: "'dialog' | 'none'", description: 'ARIA role on the content wrapper. Use "dialog" for genuine dialog content; use "none" for listbox/menu popups whose own content role should be exposed and whose trigger keeps DOM focus.', default: "'dialog'"},
+ {name: 'isModal', type: 'boolean', description: 'Whether a dialog-role popover is modal (aria-modal). Only applies when role is "dialog".', default: 'true'},
{name: 'hasSurface', type: 'boolean', description: 'Whether to apply the default popover surface background, radius, and shadow.', default: 'true'},
],
returns: [
@@ -27,7 +29,7 @@ export const docs = {
{name: 'isOpen', type: 'boolean', description: 'Whether the popover is currently open.'},
{name: 'id', type: 'string', description: 'Unique ID for aria-describedby or aria-controls.'},
{name: 'render', type: '(children: ReactNode, props?: ContextRenderProps) => ReactNode', description: 'Render function for anchor-positioned popover content. Pass placement and alignment here.'},
- {name: 'triggerProps', type: '{aria-haspopup: "dialog"; aria-expanded: boolean; aria-controls: string}', description: 'ARIA attributes to spread onto the trigger element.'},
+ {name: 'triggerProps', type: '{aria-haspopup: "dialog" | "true"; aria-expanded: boolean; aria-controls: string}', description: 'ARIA attributes to spread onto the trigger element. aria-haspopup reflects the popover role.'},
],
usage: {
description: 'Headless hook for click-triggered popovers with focus trapping. Combines useLayer with useFocusTrap, auto-focus, light dismiss, Escape handling, and an optional hidden close button for accessible dialog-like popover behavior. Use for custom interactive floating content that needs keyboard navigation.',
@@ -54,7 +56,9 @@ export const docsDense = {
hasAutoFocus: 'whether first focusable element receives focus on open.',
hasCloseButton: 'whether hidden keyboard close button is included.',
closeButtonLabel: 'label for hidden close button.',
- dialogLabel: 'accessible label for popover dialog.',
+ dialogLabel: 'accessible label for popover dialog (role="dialog" only).',
+ role: 'content wrapper ARIA role; "none" for listbox/menu popups.',
+ isModal: 'whether a dialog-role popover is modal (aria-modal).',
hasSurface: 'apply default surface background/radius/shadow.',
},
returnDescriptions: {
diff --git a/packages/core/src/Popover/usePopover.tsx b/packages/core/src/Popover/usePopover.tsx
index e9a52ff4f1..d0ffd2b668 100644
--- a/packages/core/src/Popover/usePopover.tsx
+++ b/packages/core/src/Popover/usePopover.tsx
@@ -130,10 +130,35 @@ export interface UsePopoverOptions {
/**
* Accessible label for the dialog.
- * Required for screen readers to announce the dialog purpose.
+ * Required for screen readers to announce the dialog purpose
+ * (only applies when `role` is `'dialog'`).
*/
dialogLabel?: string;
+ /**
+ * ARIA role stamped on the popover content wrapper.
+ *
+ * - `'dialog'` (default): the wrapper is a `role="dialog"` and, when
+ * `isModal` is true, carries `aria-modal`. Use for genuine dialog content.
+ * - `'none'`: the wrapper carries no role or `aria-modal`, so the popup's own
+ * content role (e.g. a child `role="listbox"` or `role="menu"`) is the
+ * exposed semantics. Use for comboboxes, listboxes, and menus — their
+ * trigger keeps DOM focus, so announcing an unnamed modal dialog around
+ * them is incorrect.
+ *
+ * @default 'dialog'
+ */
+ role?: 'dialog' | 'none';
+
+ /**
+ * Whether the dialog is modal (`aria-modal`). Only applies when `role` is
+ * `'dialog'`. Set to `false` for non-modal dialogs that do not inert the rest
+ * of the page.
+ *
+ * @default true
+ */
+ isModal?: boolean;
+
/**
* Whether to apply the default popover surface (background, border-radius,
* box-shadow) to the content wrapper.
@@ -215,7 +240,7 @@ export interface UsePopoverReturn {
* ARIA attributes to spread on the trigger element
*/
triggerProps: {
- 'aria-haspopup': 'dialog';
+ 'aria-haspopup': 'dialog' | 'true';
'aria-expanded': boolean;
'aria-controls': string;
};
@@ -274,6 +299,8 @@ export function usePopover(
hasCloseButton = true,
closeButtonLabel = 'Close popover',
dialogLabel,
+ role = 'dialog',
+ isModal = true,
} = options;
// Track the trigger element for returning focus
@@ -339,20 +366,34 @@ export function usePopover(
// ARIA attributes for the trigger
const triggerProps = {
- 'aria-haspopup': 'dialog' as const,
+ 'aria-haspopup': role === 'dialog' ? ('dialog' as const) : ('true' as const),
'aria-expanded': layer.isOpen,
'aria-controls': layer.id,
};
+ // Dev-time guardrail: a dialog popover should always be labeled. Warn once
+ // per hook instance (in an effect) rather than on every render.
+ const warnedUnnamedDialogRef = useRef(false);
+ useEffect(() => {
+ if (role === 'dialog' && !dialogLabel && !warnedUnnamedDialogRef.current) {
+ warnedUnnamedDialogRef.current = true;
+ console.warn(
+ 'usePopover: role="dialog" without a `dialogLabel` renders an unnamed ' +
+ 'dialog. Pass `dialogLabel`, or use `role: "none"` for listbox/menu ' +
+ 'popups whose content already carries its own role.',
+ );
+ }
+ }, [role, dialogLabel]);
+
// Wrapped render function that includes surface styles and optional hidden close button
const render = useCallback(
(children: ReactNode, props?: ContextRenderProps): ReactNode => {
return layer.render(
<div
ref={contentRef}
- role="dialog"
- aria-modal="true"
- aria-label={dialogLabel}
+ role={role === 'dialog' ? 'dialog' : undefined}
+ aria-modal={role === 'dialog' && isModal ? true : undefined}
+ aria-label={role === 'dialog' ? dialogLabel : undefined}
{...stylex.props(
styles.contentWrapper,
hasSurface && styles.surface,
@@ -379,6 +420,8 @@ export function usePopover(
closeButtonLabel,
contentRef,
dialogLabel,
+ role,
+ isModal,
xstyle,
],
);
diff --git a/packages/core/src/PowerSearch/PowerSearch.tsx b/packages/core/src/PowerSearch/PowerSearch.tsx
index ee9ec36b09..cf1f208348 100644
--- a/packages/core/src/PowerSearch/PowerSearch.tsx
+++ b/packages/core/src/PowerSearch/PowerSearch.tsx
@@ -546,6 +546,9 @@ export function PowerSearch({
hasLightDismiss: true,
hasCloseButton: false,
hasAutoFocus: false,
+ // The popup's own listbox/menu content is the exposed semantics; focus
+ // stays on the tokenizer input, so a modal dialog wrapper is incorrect.
+ role: 'none',
});
// Wrapper that manages layer visibility and tokenizer focus alongside state
diff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsx
index 936d586c52..81a70fdaa9 100644
--- a/packages/core/src/Selector/Selector.test.tsx
+++ b/packages/core/src/Selector/Selector.test.tsx
@@ -150,6 +150,25 @@ describe('Selector', () => {
expect(screen.getByTestId('option-badge')).toHaveTextContent('Owner');
});
+ it('exposes the popup as a listbox, not a modal dialog', () => {
+ render(
+ <Selector
+ label="Fruit"
+ options={OPTIONS}
+ value="Banana"
+ onChange={() => {}}
+ />,
+ );
+ // The combobox trigger keeps DOM focus; the popup must expose its own
+ // role="listbox" and must not be wrapped in a role="dialog" aria-modal
+ // element, which would tell AT the focused trigger is inert.
+ expect(screen.getByRole('listbox', {hidden: true})).toBeInTheDocument();
+ expect(screen.queryByRole('dialog', {hidden: true})).not.toBeInTheDocument();
+ expect(
+ document.querySelector('[aria-modal="true"]'),
+ ).not.toBeInTheDocument();
+ });
+
it('supports explicit menu placement', () => {
render(
<Selector
diff --git a/packages/core/src/Selector/Selector.tsx b/packages/core/src/Selector/Selector.tsx
index 43c61963c9..88fb364d0c 100644
--- a/packages/core/src/Selector/Selector.tsx
+++ b/packages/core/src/Selector/Selector.tsx
@@ -618,6 +618,9 @@ export function Selector<T extends SelectorOptionType>(
hasLightDismiss: true,
hasCloseButton: false,
hasAutoFocus: false,
+ // The popup's own role="listbox" is the exposed semantics; the trigger
+ // keeps DOM focus, so wrapping it in a modal dialog would misrepresent it.
+ role: 'none',
});
// Open dropdown on mount when isDefaultOpen is true
diff --git a/packages/core/src/TabList/TabMenu.tsx b/packages/core/src/TabList/TabMenu.tsx
index 89d233f126..19b7e41187 100644
--- a/packages/core/src/TabList/TabMenu.tsx
+++ b/packages/core/src/TabList/TabMenu.tsx
@@ -267,6 +267,9 @@ export function TabMenu({
hasLightDismiss: true,
hasCloseButton: false,
hasAutoFocus: false,
+ // The popup's own role="menu" is the exposed semantics; a modal dialog
+ // wrapper would announce an unnamed dialog around the menu.
+ role: 'none',
});
const {listRef, handleKeyDown: handleListKeyDown} =
diff --git a/packages/core/src/Typeahead/BaseTypeahead.tsx b/packages/core/src/Typeahead/BaseTypeahead.tsx
index e32c40c9ad..eb356b5573 100644
--- a/packages/core/src/Typeahead/BaseTypeahead.tsx
+++ b/packages/core/src/Typeahead/BaseTypeahead.tsx
@@ -352,6 +352,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
hasLightDismiss: true,
hasCloseButton: false,
hasAutoFocus: false,
+ // The popup's own role="listbox" is the exposed semantics; the input keeps
+ // DOM focus, so wrapping it in a modal dialog would misrepresent it.
+ role: 'none',
});
// Show the layer, deferring past the active click if a pointer is down.