Piensa cuántas veces te topas hoy en día con un menú desplegable que incluye un buscador integrado: la paleta de comandos en Notion, el selector de ramas en GitHub, el menú de acciones en Figma o el filtro de etiquetas en tu gestor de tareas. A primera vista parece un problema trivial para cualquiera que haga frontend: coges un desplegable normal, metes dentro un <input> de texto, le enganchas un filtro sobre el array y listo.
Pero prueba a cerrar los ojos, encender un lector de pantalla y moverte por ese componente usando solo el teclado. Nueve de cada diez veces te espera un desastre: el foco desaparece de golpe, el lector de pantalla se queda mudo o empieza a leer caracteres sin sentido, las flechas dejan de mover el cursor por el texto y pulsar Escape cierra la ventana equivocada o borra el formulario entero.
Jenna Smith y James Nelson, ingenieros de la librería Base UI, han publicado un estudio arquitectónico muy detallado sobre cómo diseñar un menú filtrable accesible (Filterable Menu). He revisado a fondo su enfoque y quiero desgranar contigo por qué las soluciones habituales incumplen los estándares de accesibilidad y cómo construir un componente sólido que combine navegación fluida por teclado y semántica WAI-ARIA honesta.
El principio del W3C: un rol semántico es una promesa
El primer error clásico al construir un menú con buscador es plantarle por inercia role="combobox". El razonamiento parece lógico: hay un campo de texto y debajo una lista desplegable, luego es un combobox.
Sin embargo, las guías de buenas prácticas de accesibilidad W3C WAI-ARIA APG parten de una regla fundamental: «Un rol semántico es una promesa al usuario» (a role is a promise). Cuando el lector de pantalla anuncia a una persona ciega que está ante un combobox, el usuario espera un comportamiento muy concreto: escribe unas letras, elige una opción con las flechas, pulsa Enter y ese valor se rellena dentro del mismo campo de texto (como al elegir ciudad o país en un formulario de envío).
En un menú de acciones (Action Menu), en cambio, la mecánica es otra:
- Los elementos del menú no son valores de texto para completar un campo. Son comandos: «Renombrar archivo», «Duplicar», «Mover a la papelera».
- Pulsar un elemento ejecuta una acción en la aplicación y cierra el menú de inmediato.
- El campo de texto funciona solo como un colador temporal para filtrar comandos, no como un campo de datos propio.
Si etiquetas ese menú como combobox, el lector de pantalla le promete al usuario que va a rellenar un campo, pero al hacer clic se dispara una acción. Eso rompe por completo las expectativas de accesibilidad y desorienta a quien navega con tecnología de asistencia.
Por qué aria-autocomplete no sirve aquí
La segunda trampa habitual es intentar usar el atributo aria-autocomplete="list". En la especificación WAI-ARIA, ese atributo está ligado de forma estricta a controlar un popup de sugerencias mediante la pareja aria-controls y aria-haspopup.
Pero en un menú de acciones el desplegable ya está abierto: el usuario pulsó el botón y el menú ya está en pantalla. Escribir en la caja de búsqueda no abre ningún popup nuevo, sino que oculta dinámicamente los elementos de la lista que no coinciden.
Además, aparece un choque irresoluble con la tecla Escape:
- En un combobox, la primera pulsación de Escape cierra la lista de sugerencias pero deja el foco dentro del campo de texto para seguir editando.
- En un menú de acciones, pulsar Escape debe cerrar todo el menú por completo y devolver el foco físico al botón que lo abrió.
Intentar mezclar dos modelos opuestos en el mismo componente acaba siempre en parches frágiles y errores impredecibles de navegación.
La apuesta arquitectónica de Base UI: un diálogo modal
El equipo de Base UI propuso una salida limpia y rigurosa: el menú desplegable con filtro se diseña como un diálogo accesible (role="dialog"), dentro del cual conviven de forma aislada el campo de búsqueda y el menú de comandos clásico.
En el árbol de accesibilidad (Accessibility Tree), el botón que abre el menú declara aria-haspopup="dialog" y el contenedor emergente recibe role="dialog" con un aria-label claro. Al abrirlo, lectores de pantalla como VoiceOver, NVDA o JAWS anuncian sin ambigüedad que se ha entrado en un cuadro de diálogo donde viven el buscador y las acciones.
Así el usuario entiende el contexto al instante: está dentro de una ventana interactiva temporal de la que puede salir en cualquier momento con Escape o Tab.
Foco virtual: mantener el foco del DOM en el input
El siguiente obstáculo serio es gestionar el foco del teclado. Cuando el usuario abre el menú y empieza a teclear, el foco físico del navegador está dentro del <input>. Pero en cuanto pulsa «Flecha abajo» para elegir un comando, aparece un dilema:
- Si mueves el foco físico del DOM al elemento del menú
<button role="menuitem">, el foco sale de la caja de búsqueda. El usuario ya no podrá seguir escribiendo ni pulsar Backspace para corregir el filtro sin volver a pinchar en el input. - Si dejas el foco en el input sin avisar al lector de pantalla, la persona ciega no escuchará qué opción está resaltada ahora mismo.
Esquema infográfico del foco virtual en el DOM: el foco de entrada permanece en el campo de búsqueda mientras aria-activedescendant enlaza la navegación con el elemento del menú.
Para resolver esta contradicción, los ingenieros de Base UI recurrieron al foco virtual mediante el atributo aria-activedescendant.
El foco físico de escritura se queda siempre dentro del <input>. Cuando el usuario pulsa las flechas arriba o abajo, el foco del DOM no se mueve: el campo sigue recibiendo letras con total normalidad. Lo que cambia el script es el valor de aria-activedescendant en el input, apuntando al identificador del elemento del menú activo en ese momento (por ejemplo, aria-activedescendant="action-rename").
El lector de pantalla detecta el cambio de ese atributo y lee de inmediato el nombre del comando resaltado, mientras que quien mira la pantalla ve el típico fondo de selección sobre la fila. Ambos perfiles disfrutan de una experiencia coherente y sin fricciones.
Detalles finos de teclado: Home, End y Tab
Cuando un editor de texto y una lista de comandos comparten el mismo componente, las teclas estándar de navegación entran en conflicto. Base UI definió reglas estrictas para resolver cada choque.
Comportamiento de Home y End:
- Si ya hay texto escrito en el filtro, Home y End hacen su trabajo natural: llevan el cursor al principio o al final de la línea escrita.
- Si el campo de búsqueda está vacío, pulsar Home selecciona al instante el primer elemento del menú y End salta al último elemento disponible.
Comportamiento de Tab: pulsar Tab cierra el menú con normalidad y pasa el foco al siguiente elemento de la página, sin atrapar el foco (focus trap). El input se declara como type="text" con rol explícito role="searchbox", evitando así que aparezcan botones nativos de borrado (la típica «X») que rompen el diseño en WebKit y Chromium.
import { Menu } from '@base-ui/react/menu';
export function ActionMenu() {
return (
<Menu.FilterProvider>
<Menu.Root>
<Menu.Trigger aria-haspopup="dialog">Действия</Menu.Trigger>
<Menu.Portal>
<Menu.Positioner>
<Menu.Popup role="dialog" aria-label="Меню действий">
<Menu.Input
type="text"
role="searchbox"
aria-label="Фильтровать действия"
placeholder="Поиск команды..."
/>
<Menu.Clear aria-label="Очистить поиск" />
<Menu.Empty>Команды не найдены</Menu.Empty>
<Menu.List>
<Menu.Item id="action-rename">Переименовать</Menu.Item>
<Menu.Item id="action-duplicate">Дублировать</Menu.Item>
<Menu.Item id="action-delete">Удалить</Menu.Item>
</Menu.List>
</Menu.Popup>
</Menu.Positioner>
</Menu.Portal>
</Menu.Root>
</Menu.FilterProvider>
);
}
Veamos ahora cómo queda por dentro la lógica de separación de teclas en el manejador de eventos del input:
function handleInputKeyDown(
event: React.KeyboardEvent<HTMLInputElement>,
activeItemId: string | null,
menuItems: string[]
) {
const input = event.currentTarget;
const isTextEmpty = input.value.length === 0;
switch (event.key) {
case 'Home':
if (isTextEmpty && menuItems.length > 0) {
event.preventDefault();
setVirtualActiveDescendant(menuItems[0]);
}
break;
case 'End':
if (isTextEmpty && menuItems.length > 0) {
event.preventDefault();
setVirtualActiveDescendant(menuItems[menuItems.length - 1]);
}
break;
case 'ArrowDown':
event.preventDefault();
moveToNextMenuItem(activeItemId, menuItems);
break;
case 'ArrowUp':
event.preventDefault();
moveToPreviousMenuItem(activeItemId, menuItems);
break;
}
}
Si tu menú tiene submenús en cascada de varios niveles, cada submenú debe ir envuelto en su propio proveedor independiente Menu.FilterProvider. De lo contrario, los identificadores de foco virtual del nivel superior y del inferior chocarán entre sí y el lector de pantalla empezará a anunciar elementos ocultos de la rama vecina.
Lecciones de ingeniería para sistemas de diseño
El trabajo del equipo de Base UI deja muy claro que la accesibilidad no es un simple visto bueno en una auditoría de Lighthouse, sino una disciplina de ingeniería seria que exige entender a fondo los eventos del navegador y los estándares del W3C.
Al diseñar componentes para tu propio sistema de diseño conviene tener presentes tres reglas básicas:
- No confundas un menú de comandos con un selector de valores: si hacer clic ejecuta una acción, usa semántica de diálogo y menú, nunca de combobox.
- No le robes el foco al usuario: el direccionamiento virtual con
aria-activedescendantmantiene intacta la escritura mientras navegas por la lista. - Respeta los atajos del sistema: un comportamiento predecible de Home, End, Tab y Escape marca la diferencia entre una interfaz madura y un parche improvisado.

