React
Explica cómo construir componentes React accesibles con HTML semántico, teclado, foco, labels, ARIA, contenido dinámico, portals y pruebas por comportamiento.
React puede renderizar HTML accesible, pero no corrige una estructura incorrecta ni convierte controles personalizados en equivalentes nativos. La accesibilidad forma parte del contrato del componente desde su diseño.
El navegador ya ofrece semántica, navegación por teclado, foco y comportamiento para muchos controles:
<button type="button" onClick={handleSave}>
Guardar cambios
</button>No reemplaces ese comportamiento con un elemento genérico:
<div onClick={handleSave}>Guardar cambios</div>Añadir role="button" no implementa automáticamente:
Tab.Enter y Space.Usa elementos nativos siempre que representen la interacción.
JSX expresa la estructura, pero las reglas pertenecen al documento resultante:
<nav aria-label="Navegación principal">
<ul>
<li><a href="/projects">Proyectos</a></li>
<li><a href="/services">Servicios</a></li>
</ul>
</nav>React no hace accesible una navegación por el hecho de dividirla en componentes. Debes conservar landmarks, listas, headings y relaciones válidas.
Utiliza un botón para una acción y un enlace para navegación:
<button type="button" onClick={openDialog}>Abrir detalles</button>
<a href="/portfolio">Ver portafolio</a>No uses un enlace vacío para ejecutar una acción ni un botón para cambiar de URL sin una razón de arquitectura.
function EmailField() {
return (
<div>
<label htmlFor="email">Correo electrónico</label>
<input
id="email"
name="email"
type="email"
autoComplete="email"
required
/>
</div>
);
}En JSX se usa htmlFor; React genera el atributo for correspondiente.
Un placeholder no reemplaza el label porque desaparece al escribir y suele tener menor contraste.
Una instancia reutilizable necesita IDs únicos:
import { useId } from "react";
function PasswordField() {
const id = useId();
const inputId = `${id}-input`;
const helpId = `${id}-help`;
return (
<div>
<label htmlFor={inputId}>Contraseña</label>
<input
id={inputId}
type="password"
name="password"
aria-describedby={helpId}
/>
<p id={helpId}>Mínimo ocho caracteres.</p>
</div>
);
}useId genera identificadores compatibles con server rendering e hydration. No lo utilices como key de listas; las keys deben provenir de la identidad de los datos.
Relaciona el mensaje con el campo:
type EmailFieldProps = {
error?: string;
};
function EmailField({ error }: EmailFieldProps) {
const id = useId();
const errorId = `${id}-error`;
return (
<div>
<label htmlFor={id}>Correo</label>
<input
id={id}
name="email"
type="email"
aria-invalid={Boolean(error)}
aria-describedby={error ? errorId : undefined}
/>
{error && (
<p id={errorId} role="alert">
{error}
</p>
)}
</div>
);
}No anuncies cada validación mientras el usuario escribe si eso genera ruido. El momento adecuado depende del producto: blur, submit o validación progresiva cuidadosamente diseñada.
React no exige reemplazar validaciones HTML:
<input type="email" required minLength={5} />La validación de producto puede complementar estas reglas. El servidor debe volver a validar porque el cliente puede alterarse.
Un componente interactivo debe definir:
Para patrones complejos como tabs, menu, combobox o grid, sigue especificaciones accesibles probadas o utiliza primitives headless mantenidas.
No inventes un modelo de teclado distinto sin necesidad.
No elimines el outline sin una alternativa:
.button:focus-visible {
outline: 3px solid var(--focus-ring);
outline-offset: 3px;
}El foco visible pertenece principalmente a CSS, pero el componente debe permitir que los elementos correctos reciban foco.
Mover el foco es apropiado cuando cambia el contexto de interacción:
No muevas el foco por cada render o actualización menor.
function EditDialog({ open, onClose }: DialogProps) {
const closeButtonRef = useRef<HTMLButtonElement>(null);
useEffect(() => {
if (open) closeButtonRef.current?.focus();
}, [open]);
if (!open) return null;
return (
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
<h2 id="dialog-title">Editar perfil</h2>
<button ref={closeButtonRef} type="button" onClick={onClose}>
Cerrar
</button>
</div>
);
}Un modal real también necesita contener el foco, cerrar con Escape cuando corresponda, volver al trigger y evitar interacción con el fondo. El elemento nativo <dialog> puede resolver parte del comportamiento, pero aún requiere diseño y pruebas.
Un portal cambia la ubicación DOM, no la pertenencia al árbol React. Context y propagación de eventos React continúan según el árbol de componentes.
Para accesibilidad debes considerar la ubicación real:
aria-modal.Portals no solucionan automáticamente modales ni stacking contexts.
Cada pantalla necesita una estructura comprensible:
<main>
<h1>Configuración de la cuenta</h1>
<section aria-labelledby="privacy-heading">
<h2 id="privacy-heading">Privacidad</h2>
</section>
</main>No elijas un heading por su tamaño visual. El estilo pertenece a CSS; el nivel comunica jerarquía.
Cuando el contenido es una colección, conserva la semántica:
<ul>
{notifications.map((notification) => (
<li key={notification.id}>{notification.message}</li>
))}
</ul>Fragments y componentes no deben producir hijos inválidos de ul, table, dl u otras estructuras con reglas específicas.
Una tabla de datos necesita encabezados reales:
<table>
<caption>Pedidos recientes</caption>
<thead>
<tr>
<th scope="col">Número</th>
<th scope="col">Estado</th>
</tr>
</thead>
<tbody>
{orders.map((order) => (
<tr key={order.id}>
<th scope="row">{order.number}</th>
<td>{order.status}</td>
</tr>
))}
</tbody>
</table>No uses tablas para layout visual.
Para mensajes que deben anunciarse sin mover foco:
<p role="status" aria-live="polite">
{statusMessage}
</p>role="status" ya implica una live region polite en muchos contextos.
Usa role="alert" para información urgente. Anunciar cada cambio pequeño puede interrumpir y saturar al usuario.
Una región pendiente puede comunicar su estado:
<section aria-busy={isPending} aria-labelledby="results-heading">
<h2 id="results-heading">Resultados</h2>
<Results />
</section>Cuando Suspense reemplaza contenido con fallback:
Un icono visible no garantiza un nombre accesible:
<button type="button" aria-label="Eliminar producto" onClick={handleDelete}>
<TrashIcon aria-hidden="true" />
</button>Cuando existe texto visible, normalmente ese texto ya aporta el nombre:
<button type="button">
<TrashIcon aria-hidden="true" />
Eliminar
</button>El alt depende del propósito:
<img src={product.imageUrl} alt={product.name} />Para una imagen decorativa:
<img src="/decorative-wave.svg" alt="" />No repitas en el alt información idéntica que ya está junto a la imagen si no aporta contexto.
Primera regla práctica:
Si un elemento HTML nativo expresa el comportamiento, úsalo antes de recrearlo con ARIA.
ARIA puede comunicar estados y relaciones:
<button
type="button"
aria-expanded={open}
aria-controls={panelId}
onClick={() => setOpen((value) => !value)}
>
Filtros
</button>
<div id={panelId} hidden={!open}>...</div>ARIA no añade comportamiento. aria-expanded no abre ni cierra el panel; el componente debe implementarlo.
React controla cuándo aparece una animación; CSS puede respetar preferencias:
@media (prefers-reduced-motion: reduce) {
.animated-panel {
transition: none;
}
}No bases información esencial únicamente en movimiento.
Contraste, tamaño, spacing y estados hover/focus pertenecen principalmente a CSS y diseño. El componente debe exponer estados claros mediante clases, atributos y estructura semántica.
Una primitive headless accesible puede resolver comportamiento complejo sin imponer estilos.
Aun así debes verificar:
React Testing Library recomienda consultas cercanas a cómo una persona encuentra el elemento:
const saveButton = screen.getByRole("button", { name: /guardar cambios/i });
await user.click(saveButton);Si no puedes encontrar un control por rol y nombre, puede existir un problema en su semántica.
Complementa tests automáticos con:
Las herramientas automáticas no detectan toda la experiencia.
onClick a un div y considerarlo botón.useId como key.role="alert".htmlFor, ARIA y atributos del DOM.useId crea IDs estables, no keys de listas.role="button" no convierte completamente un div en botón?useId y para qué no debe utilizarse?getByRole puede detectar problemas de diseño accesible?Debugging, StrictMode y React DevTools explica cómo detectar warnings, renders inesperados, problemas de keys, hydration y ciclos de effects.