treeitem

Cuándo utilizarlo

Dentro de un role="tree", en cada nodo visible. Si el nodo tiene hijos, se debe establecer aria-expanded="true" o "false" y contener o poseer un role="group" que albergue los treeitems hijos. Si el nodo no tiene hijos, se debe omitir aria-expanded por completo (NO establecerlo en "false" en una hoja — eso anunciaría «contraído» sin que haya nada que expandir).

Se debe establecer aria-level (profundidad con índice 1), aria-posinset (posición entre los hermanos, con índice 1) y aria-setsize (total de hermanos) en cada treeitem cuando el anidamiento visual no puede inferirse de la jerarquía del DOM.

Para una navegación que consiste simplemente en «una lista de enlaces con sub-enlaces anidados», <nav> con <ul> anidados y <a> es la mejor opción. Se debe usar treeview únicamente cuando la experiencia es un navegador jerárquico con un único punto de tabulación.

Contrato de teclado y foco

Según el patrón de treeview de la APG:

• Tab desplaza el foco hacia el interior del árbol, al treeitem activo; Tab lo desplaza hacia fuera.
• Las flechas Arriba/Abajo mueven el foco entre los nodos visibles (saltando los hijos contraídos).
• Flecha Derecha: si el nodo está contraído, lo expande; si está expandido, mueve el foco al primer hijo.
• Flecha Izquierda: si el nodo está expandido, lo contrae; si está contraído, mueve el foco al padre.
• Inicio / Fin mueven el foco al primer / último nodo visible.
• Intro o Espacio activan (seleccionan) el elemento actual.
• Teclado anticipatorio: al escribir una letra, el foco se desplaza al siguiente nodo visible que coincida.

Errores frecuentes

• aria-expanded="false" en un nodo hoja — anuncia un estado colapsable fantasma.
• Cada treeitem lleva tabindex="0". El patrón es de único punto de tabulación; solo el elemento enfocado tiene tabindex="0".
• Las flechas Derecha/Izquierda usadas para «siguiente hermano / hermano anterior» en lugar de expandir/contraer.
• Los treeitems hijos colocados directamente dentro del <li> padre sin un role="group" envolvente. Los lectores de pantalla no pueden anunciar el grupo como una unidad.
• Ausencia de aria-level cuando el DOM es plano (por ejemplo, cuando el árbol se renderiza con posicionamiento absoluto).

Ejemplo

<ul role="tree" aria-label="Files">
  <li role="treeitem" aria-expanded="true" tabindex="0">
    Documents
    <ul role="group">
      <li role="treeitem" tabindex="-1">Resume.pdf</li>
      <li role="treeitem" aria-expanded="false" tabindex="-1">
        Photos
        <ul role="group">
          <li role="treeitem" tabindex="-1">2025-summer.jpg</li>
        </ul>
      </li>
    </ul>
  </li>
  <li role="treeitem" tabindex="-1">Downloads</li>
</ul>