aria-haspopup

Cuándo utilizarlo

En cualquier control que abra una superposición transitoria: un botón que dispara un menú, un campo de texto que abre una lista desplegable en un combobox, o un botón de icono que muestra un diálogo. El atributo permite que el lector de pantalla anuncie algo como «Filtrar, botón de menú» o «Buscar, tiene ventana emergente», de modo que el usuario sabe que al activar el control se mostrará más interfaz en lugar de navegar o enviar un formulario.

Omítalo en los controles que simplemente alternan una sección de la misma página: un widget de divulgación debe utilizar aria-expanded por sí mismo; el contenido que se muestra es parte de la página, no una ventana emergente.

Comportamiento

Acepta un conjunto fijo de valores de token:

• "menu" — abre un role="menu" (el caso más habitual en botones de menú).
• "listbox" — abre un role="listbox", empleado en comboboxes personalizados.
• "tree" — abre un role="tree".
• "grid" — abre un role="grid" (frecuente en selectores de fecha).
• "dialog" — abre un role="dialog" o role="alertdialog".
• "true" — equivalente a "menu" por razones de compatibilidad con versiones anteriores; prefiera uno de los valores específicos.
• "false" — indica explícitamente «no tiene ventana emergente»; es el valor predeterminado.

Combine aria-haspopup con aria-expanded="true|false" para que la AT también pueda anunciar si la ventana emergente está visible en ese momento. Los dos atributos cumplen funciones distintas: haspopup indica «existe una ventana emergente» y expanded indica «y actualmente está visible».

Errores frecuentes

• Usar aria-haspopup="true" en un botón que abre un selector de fecha personalizado (que en realidad es un grid o un diálogo): la AT anuncia «botón de menú» y el usuario presiona la flecha hacia abajo esperando elementos de menú.
• Olvidar aria-expanded. La AT dice «tiene ventana emergente» pero nunca anuncia el estado abierto o cerrado, por lo que el usuario no puede saber si su clic tuvo efecto.
• Añadir aria-haspopup a un control que en realidad no abre ninguna ventana emergente. Induce a error al usuario, que escucha la prestación y no encuentra nada.
• Usar aria-haspopup en un enlace que navega a una nueva página. No es una ventana emergente; deje que el enlace sea simplemente un enlace.
• Olvidar mover el foco al interior de un popup de tipo dialog o al primer menuitem de un menu. El atributo nombra el tipo de ventana emergente, pero no gestiona el foco.
• Establecer aria-haspopup="dialog" sin asignar role="dialog" a la ventana emergente. La semántica prometida nunca aparece.

Ejemplo

<!-- Botón de menú -->
<button
  type="button"
  id="filter-btn"
  aria-haspopup="menu"
  aria-expanded="false"
  aria-controls="filter-menu"
>
  Filtrar
</button>
<ul id="filter-menu" role="menu" hidden>
  <li role="menuitem">Todo</li>
  <li role="menuitem">No leído</li>
  <li role="menuitem">Marcado</li>
</ul>