Roles, estados y propiedades ARIA

Región activa que transmite un mensaje urgente y sensible al tiempo. Los lectores de pantalla lo anuncian de inmediato, interrumpiendo la locución actual. Debe usarse con moderación — reservado para errores y advertencias genuinas; el abuso provoca fatiga en las tecnologías de asistencia.

Un diálogo que transmite un mensaje urgente y requiere respuesta del usuario. Combina la semántica de diálogo con el anuncio de alerta. Debe usarse únicamente para confirmaciones destructivas, errores que bloquean el trabajo o interrupciones que no pueden esperar.

Marca una composición autónoma que puede sostenerse por sí sola: una entrada de blog, una noticia, una respuesta en un foro o una tarjeta de producto. Se recomienda usar el elemento nativo <article>; solo se debe recurrir a role="article" cuando no sea posible utilizar el elemento HTML.

HTML nativo: <article>

El punto de referencia del encabezado de todo el sitio — habitualmente contiene el logotipo, la navegación principal y el buscador. El elemento <header> de nivel superior adopta este rol de forma automática. Solo puede existir un banner por página.

HTML nativo: <header> (top-level)

Marca un elemento como botón — un control que desencadena una acción al activarse. Use primero el elemento HTML nativo <button>; recurra a role="button" en un <div> o <span> solo cuando no sea posible usar el elemento nativo.

HTML nativo: <button>

Marca un elemento como casilla de verificación de dos o tres estados. Se recomienda usar <input type="checkbox"> en primer lugar; recurra a role="checkbox" solo cuando no pueda utilizar el elemento nativo — por ejemplo, al construir un control de tres estados que deba mostrar un valor mixto.

HTML nativo: <input type="checkbox">

Marca una entrada de texto asociada a una lista emergente de valores — se usa para autocompletar, búsqueda por escritura anticipada y selectores personalizados. Recurra a role="combobox" solo cuando necesite filtrado, renderizado personalizado o sugerencias remotas; para selección simple use el <select> nativo.

HTML nativo: <select>

Punto de referencia para contenido que apoya el contenido principal pero tiene sentido por sí solo: barras laterales, cajas de artículos relacionados, recuadros complementarios. El elemento <aside> lleva este rol cuando se encuentra en el nivel superior.

HTML nativo: <aside>

El punto de referencia del pie de sitio — derechos de autor, contacto, enlaces legales. El elemento <footer> de nivel superior lleva este rol automáticamente. Solo puede existir un contentinfo por página.

HTML nativo: <footer> (top-level)

Marca un elemento como la definición de un término. Debe emparejarse con role="term" (o el elemento nativo <dfn>) para asociar el término con su definición. Se recomienda usar primero <dl>/<dt>/<dd> o <dfn>, ya que aportan la semántica de forma nativa.

HTML nativo: <dfn>

Marca un contenedor como un diálogo modal o no modal. Utilice el elemento nativo <dialog> con showModal() — gestiona de forma automática el confinamiento del foco, la capa superior, el telón de fondo y el cierre con Escape. Recurra a role="dialog" solo cuando el elemento nativo sea imposible de usar.

HTML nativo: <dialog>

Marca un bloque ilustrativo autónomo — imagen, diagrama, listado de código — habitualmente acompañado de un pie de figura. Se recomienda usar el elemento nativo <figure>; solo se debe recurrir a role="figure" cuando el elemento anfitrión no pueda ser un <figure>.

HTML nativo: <figure>

Un punto de referencia para un formulario — un conjunto de controles de entrada que envían datos. Un elemento <form> se expone como punto de referencia de formulario ÚNICAMENTE cuando tiene un nombre accesible. Sin nombre, es simplemente un formulario, no un punto de referencia.

HTML nativo: <form aria-label>

Marca una agrupación genérica de elementos relacionados. Tiene menos peso semántico que un punto de referencia — los lectores de pantalla no lo anuncian en el menú de puntos de referencia. Para controles de formulario se prefiere <fieldset> + <legend>; role="group" aplica a agrupaciones que no sean de formulario.

HTML nativo: <fieldset>

Marca un elemento como encabezado. Utilice primero <h1>–<h6>, ya que proporcionan la semántica correcta y el nivel adecuado de forma nativa. Recurra a role="heading" solo cuando sea imprescindible actualizar semánticamente un elemento que no puede ser un <h*>.

HTML nativo: <h1> – <h6>

Marca un elemento como hipervínculo: un control que navega a un nuevo recurso cuando se activa. Se debe usar el elemento nativo HTML <a href> en primer lugar; solo se debe recurrir a role="link" en un <span> o <div> cuando no haya forma de utilizar el elemento nativo.

HTML nativo: <a href>

Marca un elemento como una lista de ítems. Se deben usar <ul>, <ol> o <dl> en primer lugar: el elemento nativo gestiona el rol, el recuento y el marcador visual. Solo se debe recurrir a role="list" cuando la propiedad CSS list-style: none activa la eliminación del rol de lista en Safari.

HTML nativo: <ul> / <ol>

Marca un elemento como una lista de opciones seleccionables. Se recomienda usar <select> para el caso simple de selección única. Recurrir a role="listbox" cuando se necesite estilo personalizado, selección múltiple con renderizado propio o combinación con un combobox.

HTML nativo: <select> (selección única)

Marca un elemento como un ítem dentro de una lista. Se recomienda usar <li> dentro de <ul> o <ol> — el elemento nativo incluye el rol y la posición en el conjunto. Se debe recurrir a role="listitem" únicamente cuando se combine con un role="list" explícito en un elemento padre que no sea una lista.

HTML nativo: <li>

El punto de referencia del contenido principal — el contenido primario de la página, excluyendo encabezados repetidos, navegación y pies de página. El elemento <main> incorpora este rol de forma automática. Debe existir exactamente un main por página.

HTML nativo: <main>

Marca un contenedor como menú de aplicación — el desplegable de menús al estilo Archivo/Edición o los menús contextuales. No existe equivalente HTML. Una lista de navegación del sitio NO es un menu; se debe usar <nav> con <ul> de enlaces.

Marca un contenedor como barra de menú persistente — la franja horizontal siempre visible con menús al estilo Archivo/Edición/Ver de las aplicaciones de escritorio. Distinto de menu, que es un desplegable. Casi nunca es el patrón adecuado en la web.

Marca un elemento como una opción accionable dentro de un menú o barra de menú. No existe un equivalente HTML — los menús son una construcción exclusiva de ARIA. Use este rol solo cuando esté construyendo un menú de aplicación real (estilo escritorio); una lista de navegación común NO debe usar menu/menuitem.

Un punto de referencia (landmark) que agrupa un conjunto de enlaces de navegación: nav principal, migas de pan, tabla de contenidos. El elemento <nav> incluye este rol de forma implícita. Es habitual y correcto tener varios nav en una misma página, pero cada uno debe tener un nombre accesible distinto.

HTML nativo: <nav>

Marca un elemento seleccionable dentro de un listbox. Una option DEBE ser descendiente de un listbox (directamente o a través de aria-owns). Se debe usar el elemento nativo <option> dentro de <select>; solo se recurrirá a role="option" cuando se construya un listbox personalizado o un menú emergente de combobox.

HTML nativo: <option>

Marca un elemento como indicador de progreso. Se recomienda usar <progress> en primer lugar, ya que incluye semántica, representación visual y atributos de valor de forma nativa. Solo se debe recurrir a role="progressbar" cuando sea necesario aplicar estilos más allá de lo que permite el elemento nativo.

HTML nativo: <progress>

Marca un elemento como una opción única dentro de un grupo mutuamente excluyente. Un radio debe estar dentro de un radiogroup (o un fieldset nativo). Se recomienda usar <input type="radio"> en primer lugar; solo se debe recurrir a role="radio" cuando el elemento nativo sea imposible de usar.

HTML nativo: <input type="radio">

Un punto de referencia genérico para contenido que no encaja en banner, main, navigation, complementary ni contentinfo, pero que sigue siendo lo suficientemente importante como para navegar hasta él. Un <section> se convierte en punto de referencia region cuando, y solo cuando, tiene un nombre accesible.

HTML nativo: <section aria-label>

Hito que agrupa un formulario de búsqueda. Permite a los usuarios de lectores de pantalla saltar directamente a la búsqueda del sitio. El elemento nativo <search> (HTML 2024) incluye este rol automáticamente; use role="search" en un <form> para mayor compatibilidad con navegadores actuales.

HTML nativo: <search>

Marca un elemento como campo de texto para tareas de búsqueda. Se recomienda usar primero <input type="search"> — proporciona la interfaz del botón de borrado y la semántica de búsqueda automáticamente. Recurrir a role="searchbox" solo para un campo de búsqueda personalizado basado en contenteditable.

HTML nativo: <input type="search">

Marca un elemento como divisor entre secciones de contenido o elementos de un widget compuesto. Se recomienda usar <hr> para las separaciones temáticas en el texto continuo; solo se debe recurrir a role="separator" para separar elementos dentro de un menú, una barra de herramientas u otro widget.

HTML nativo: <hr>

Marca un elemento como entrada que selecciona un valor dentro de un rango. Se recomienda usar <input type="range"> en primer lugar; solo se debe recurrir a role="slider" cuando se necesite una pista personalizada — por ejemplo, un selector de rango de dos pulgadores, que el elemento nativo no admite.

HTML nativo: <input type="range">

Región activa que transmite información orientativa no urgente. Los lectores de pantalla anuncian los cambios de forma educada — en la próxima pausa del habla, sin interrumpir. Úsese para confirmaciones rutinarias, recuentos y actualizaciones de progreso. El elemento nativo <output> lleva este rol.

HTML nativo: <output>

Marca un elemento como interruptor de encendido/apagado. Funcionalmente similar a una casilla de verificación, pero se anuncia como "switch, encendido" o "switch, apagado" en lugar de "marcado" — encaja mejor con un control de alternancia en ajustes. Todavía no existe un equivalente HTML nativo.

Marca un elemento como una pestaña dentro de una interfaz con pestañas. Una pestaña DEBE residir dentro de un tablist y DEBERÍA referenciar su tabpanel asociado mediante aria-controls. No existe ningún elemento HTML nativo equivalente — las pestañas son un patrón exclusivo de ARIA.

Marca un contenedor como la barra de pestañas de una interfaz con pestañas. Agrupa los elementos hijos con role="tab". Las pestañas y los tabpanels son un patrón exclusivo de ARIA — no existe ningún elemento HTML nativo equivalente.

Marca el panel de contenido asociado a una pestaña. Cada tabpanel recibe su nombre de su pestaña mediante aria-labelledby; la pestaña referencia el panel mediante aria-controls. Se muestra un panel a la vez; los demás se ocultan con el atributo hidden.

Marca un elemento como campo de texto de una o varias líneas. Se recomienda usar <input type="text"> o <textarea> en primer lugar — gestionan todos los comportamientos del cuadro de texto de forma nativa. Recurra a role="textbox" solo al construir un editor de texto enriquecido sobre un elemento contenteditable.

HTML nativo: <input type="text"> / <textarea>

Marca un contenedor como barra de herramientas — un conjunto agrupado de controles relacionados (una barra de formato, una fila de botones de icono). Reduce el coste de tabulación: una barra con 10 botones se convierte en un único punto de tabulación; las teclas de flecha permiten moverse entre los botones.

Marca un elemento como contenedor jerárquico de treeitems — un explorador de archivos, categorías anidadas o un organigrama. Punto de tabulación único, navegación con teclas de flecha, expandir/contraer. No existe un equivalente nativo en HTML.

Marca un elemento como nodo dentro de un árbol. Un treeitem puede ser expandible (padre de más treeitems) o terminal (hoja). Úsese únicamente al construir un navegador jerárquico — explorador de archivos, organigrama, categorías anidadas — que requiera navegación con flechas y un único punto de tabulación.

Controla si la tecnología de asistencia anuncia el contenido completo de una región en vivo al actualizarse o solo la parte que cambió. El valor predeterminado es "false" (solo la diferencia). Se debe establecer "true" cuando el contexto solo tiene sentido como oración completa.

Marca una región como en proceso de actualización para que la tecnología de asistencia suprima los anuncios intermedios. Se establece en "true" mientras se carga o mientras se producen cambios importantes en el DOM; debe volver a "false" cuando la región sea estable.

Indica el estado de marcado actual de una casilla de verificación, botón de opción o elemento de menú de tipo casilla. Acepta "true", "false" o "mixed". La casilla de verificación HTML nativa gestiona esto de forma automática — establézcalo manualmente solo en widgets personalizados.

Marca el elemento que representa el ítem actual dentro de un conjunto — la página activa en una navegación, el paso actual en un asistente, el día de hoy en un selector de fechas. Más específico que aria-selected; se usa en enlaces y en elementos donde la selección no es la metáfora adecuada.

Indica que un control es perceptible y enfocable pero no responde a la entrada del usuario. Se prefiere el atributo HTML disabled nativo cuando está disponible; recurra a aria-disabled cuando necesite que el elemento permanezca enfocable o pueda recibir un tooltip.

Indica si un elemento desplegable — botón de divulgación, combobox, menú, treeitem — está actualmente abierto. Acepta "true" o "false". Normalmente se combina con aria-controls apuntando a la región que el control abre.

Elimina un elemento y todos sus descendientes del árbol de accesibilidad. Los usuarios videntes siguen viendo el elemento; la tecnología de asistencia nunca accede a él. Resérvelo para contenido decorativo; no lo aplique nunca a un control enfocable.

Indica que un control de formulario ha fallado la validación. Se debe combinar con aria-describedby apuntando al mensaje de error legible para que el lector de pantalla anuncie tanto el estado inválido como el motivo.

Marca una región cuyas actualizaciones deben ser anunciadas por la tecnología de apoyo sin desplazar el foco. Se recomienda «polite» para la mayoría de los casos y «assertive» únicamente para actualizaciones genuinamente urgentes. La región debe estar en el DOM desde la carga inicial.

Indica a la tecnología asistiva que trate el resto de la página como inerte mientras un diálogo está abierto. Se establece en "true" sobre role="dialog" o role="alertdialog". No convierte el fondo en inerte por sí solo — combínelo con el atributo inert o una trampa de foco.

Indica si un botón de alternancia está actualmente presionado. Se establece en "true" cuando la alternancia está activada y en "false" cuando está desactivada; la tecnología de asistencia anuncia el estado junto con la etiqueta.

Indica que el valor de un control de formulario no puede editarse, aunque el control sigue siendo operable: se puede enfocar, copiar y enviar con el formulario. Es diferente de aria-disabled, que hace que el control sea inoperable.

Indica que un elemento dentro de un contenedor de selección simple o múltiple está actualmente seleccionado. Se utiliza en los roles tab, option, gridcell, treeitem y similares. Se distingue de aria-checked (casilla de verificación/botón de opción) y de aria-pressed (botón alternante).

En un widget compuesto, señala el ID del descendiente que está activo en ese momento. El foco del DOM permanece en el contenedor mientras un foco virtual se desplaza entre los elementos hijos. Alternativa al roving tabindex para listboxes, comboboxes y grids.

En un cuadro de texto o combobox, declara qué tipo de autocompletado ofrece el control: sugerencias en línea, una lista de opciones, ambas o ninguna. Es distinto del atributo HTML autocomplete, que se ocupa de la semántica de los campos de formulario para el navegador.

Identifica el elemento o elementos cuya presencia o contenido gobierna este control. Pares habituales: una pestaña controla su tabpanel, un botón de revelación controla una región desplegada. La compatibilidad con las tecnologías de apoyo es irregular — se recomienda usarlo con moderación.

Hace referencia a uno o más IDs de elementos cuyo texto se convierte en la descripción extendida de este elemento. Se anuncia tras el nombre accesible. Se usa para texto de ayuda, indicaciones de formato y mensajes de error en línea.

Indica a la tecnología de asistencia que activar este control abrirá una ventana emergente y especifica de qué tipo. Acepta "menu", "listbox", "tree", "grid", "dialog" o "true" / "false". Combínelo con aria-expanded para que la AT también pueda anunciar si la ventana emergente está abierta.

Proporciona un nombre accesible como cadena de texto cuando no hay texto visible disponible. Se debe usar únicamente cuando no existe una etiqueta en pantalla — si hay texto visible, se prefiere aria-labelledby para que el nombre pronunciado coincida con lo que el usuario ve.

Referencia uno o varios IDs de elementos cuyo texto visible se convierte en el nombre accesible de este elemento. Se prefiere sobre aria-label cuando el texto en pantalla ya describe el control.

Indica el nivel jerárquico de un elemento dentro de una estructura. Obligatorio en elementos con role="heading"; también se utiliza en role="treeitem" y role="listitem" dentro de listas anidadas. El valor es un número entero positivo que comienza en 1.

Declara una relación padre-hijo en el árbol de accesibilidad cuando la estructura del DOM no la expresa. Reasigna los elementos referenciados como hijos de este elemento para la tecnología de apoyo. Es una herramienta potente — fácil de usar incorrectamente.

Posición de un elemento dentro de un conjunto cuando el DOM no puede expresarla — habitualmente porque los elementos están virtualizados, paginados o filtrados. Siempre se debe combinar con aria-setsize para que los lectores de pantalla puedan anunciar «3 de 47».

Indica que el usuario debe completar un control antes de poder enviar un formulario. Se debe usar el atributo HTML required en los campos de formulario nativos; solo se debe recurrir a aria-required cuando no existe un equivalente HTML, por ejemplo, un combobox construido sobre un div.

Número total de elementos de un conjunto cuando el DOM no los contiene todos. Se usa junto con aria-posinset para que un lector de pantalla pueda anunciar «elemento 14 de 5.000» aunque solo se rendericen cinco. Se debe usar -1 si el total es desconocido.

En el encabezado de una columna o fila de una cuadrícula o tabla ordenable, indica la dirección de ordenación actual. Valores: "ascending", "descending", "other" o "none". Solo un encabezado de la tabla debe llevar un valor de ordenación activo a la vez.

Valor numérico actual de un widget de tipo rango — slider, progressbar, spinbutton, scrollbar. Debe combinarse con aria-valuemin y aria-valuemax para que las tecnologías de asistencia anuncien una posición significativa. Se debe usar aria-valuetext para etiquetas no numéricas.