aria-haspopup — Indicating Popup Elements to Screen Readers

In this tutorial, you will learn about aria. We cover key concepts, practical examples, and best practices to help you master this topic.

aria-haspopup indicates that an interactive element triggers a popup widget like a menu, dialog, listbox, tree, or grid, helping screen reader users understand what will appear.

In this tutorial, you'll learn how to use aria-haspopup in ARIA.

What You'll Learn

By the end of this lesson, you'll understand the five aria-haspopup values, how to pair it with aria-expanded, and the expected keyboard interaction.

Why It Matters

Without aria-haspopup, screen reader users do not know that activating a button will open a menu, dialog, or other popup. They lose context and trust.

Real-World Use

Doda Browser's menu bar uses aria-haspopup="menu" on each top-level menu item so screen reader users know activating it opens a submenu.

Popup Types

flowchart TD
  A[aria-haspopup values] --> B[menu]
  A --> C[listbox]
  A --> D[tree]
  E[grid]
  A --> F[dialog]
  A --> G[true]
  B --> H[Submenu opens]
  C --> I[List of options opens]
  D --> J[Tree view opens]
  E --> K[Grid opens]
  F --> L[Dialog opens]
  G --> M[Unknown popup type]

How aria-haspopup Works

aria-haspopup is set on the element that triggers the popup:

<button aria-haspopup="menu" aria-expanded="false">
  File
</button>

The screen reader announces "File, button, has popup menu, collapsed".

aria-haspopup Values

<button aria-haspopup="menu">Open menu</button>
<button aria-haspopup="dialog">Open dialog</button>
<button aria-haspopup="listbox">Show options</button>

Pairing With aria-expanded

Always use aria-haspopup with aria-expanded to indicate visibility:

<button aria-haspopup="dialog" aria-expanded="true" aria-controls="settings-dialog">
  Settings
</button>
<div id="settings-dialog" role="dialog" aria-modal="true">
  <!-- dialog content -->
</div>

Common Mistakes

• Using aria-haspopup="true" instead of a specific value: Use the specific popup type.
• Forgetting aria-expanded: Tell users whether the popup is currently visible.
• Not implementing keyboard interaction: Popups must be keyboard accessible.
• Setting aria-haspopup on the popup itself: It goes on the triggering element.
• Using aria-haspopup on non-interactive elements: The trigger must be focusable.

Practice and Challenge

1. What does aria-haspopup="menu" indicate? Activating this element opens a menu.

2. What attribute should pair with aria-haspopup? aria-expanded.

3. What aria-haspopup value should you use for a modal dialog? dialog.

4. Why is aria-haspopup="true" deprecated? It does not tell users what type of popup to expect.

5. Challenge: Create a button that opens a dialog. Use aria-haspopup="dialog" and aria-expanded. Manage focus when the dialog opens and closes.

FAQ

Mini Project

Build a toolbar with a button that opens a dropdown menu. Use aria-haspopup="menu" and aria-expanded. Implement full keyboard navigation for the menu.

What's Next

Continue to aria-modal to learn about indicating modal dialogs.