Treegrid

What Is a Treegrid?

A treegrid is "a grid (table) where rows can be expanded and collapsed."Email thread lists, file/folder listings, and comment trees are common use cases — whenever you need to handle both "tabular data" and "hierarchical (parent → child) expansion."

Think of it as a regular table (table) with the added ability to collapse rows. Because of this, you need to convey both the table structure (rows, cells, headers) and tree state (expanded / collapsed) to assistive technologies.

Why Does Accessibility Matter?

Building it with visual styling alone leaves these people behind:

• Keyboard-only users. If rows are <div> elements, they can't be focused with Tab, and there's no way to navigate or expand/collapse rows with arrow keys.
• Screen reader users. Without role attributes, it's not recognized as a "table" or "row," so there's no way to know which cell belongs to which header, or whether a row is expanded or collapsed.

The solution is to convey structure with role="treegrid" / role="row" / role="gridcell", add aria-expanded to parent rows to convey expand/collapse state, and enable arrow key navigation.

Live Demo (Recommended Implementation)

Below is an email thread list implemented according to the APG. Try operating it without the mouse, using only the keyboard.

Keyboard Interaction

Required WAI-ARIA Roles & Properties

Recommended Pattern (Good)

Markup:

<table role="treegrid" aria-label="Inbox">
  <thead>
    <tr role="row">
      <th role="columnheader">From</th>
      <th role="columnheader">Subject</th>
      <th role="columnheader">Date</th>
    </tr>
  </thead>
  <tbody>
    <!-- Parent row: expandable. aria-expanded conveys open/close state -->
    <tr role="row"
        aria-level="1" aria-posinset="1" aria-setsize="2"
        aria-expanded="true" tabindex="0">
      <td role="gridcell">Yamada</td>
      <td role="gridcell">Year-end party (3 messages)</td>
      <td role="gridcell">12/10</td>
    </tr>
    <!-- Child rows: hidden while parent is collapsed -->
    <tr role="row" aria-level="2" aria-posinset="1" aria-setsize="2" tabindex="-1">
      <td role="gridcell">Yamada</td>
      <td role="gridcell">Re: Scheduling discussion</td>
      <td role="gridcell">12/10</td>
    </tr>
    <tr role="row" aria-level="2" aria-posinset="2" aria-setsize="2" tabindex="-1">
      <td role="gridcell">Sato</td>
      <td role="gridcell">Re: Restaurant booked</td>
      <td role="gridcell">12/11</td>
    </tr>
  </tbody>
</table>

Keyboard interaction and state synchronization script:

const grid = document.querySelector('[role="treegrid"]');
const rows = Array.from(grid.querySelectorAll('tbody [role="row"]'));

// Collect only currently operable (visible) rows
const visibleRows = () => rows.filter((r) => !r.hidden);

// Roving tabindex: only one row has tabindex="0", the rest are "-1"
function focusRow(row) {
  rows.forEach((r) => r.setAttribute('tabindex', r === row ? '0' : '-1'));
  row.focus();
}

// Toggle child rows (one level deeper) following a parent row
function setExpanded(row, open) {
  row.setAttribute('aria-expanded', String(open));
  let next = row.nextElementSibling;
  while (next && next.getAttribute('aria-level') === '2') {
    next.hidden = !open;        // Hidden rows are excluded from keyboard/screen reader
    next = next.nextElementSibling;
  }
}

grid.addEventListener('keydown', (e) => {
  const row = e.target.closest('[role="row"]');
  if (!row) return;
  const list = visibleRows();
  const i = list.indexOf(row);
  const expandable = row.hasAttribute('aria-expanded');
  const isOpen = row.getAttribute('aria-expanded') === 'true';
  let target = null;

  switch (e.key) {
    case 'ArrowDown': target = list[Math.min(i + 1, list.length - 1)]; break;
    case 'ArrowUp':   target = list[Math.max(i - 1, 0)]; break;
    case 'Home':      target = list[0]; break;
    case 'End':       target = list[list.length - 1]; break;
    case 'ArrowRight':
      if (expandable && !isOpen) { e.preventDefault(); setExpanded(row, true); }
      return;
    case 'ArrowLeft':
      if (expandable && isOpen) { e.preventDefault(); setExpanded(row, false); }
      return;
    default: return;
  }
  if (target) { e.preventDefault(); focusRow(target); }
});

Anti-Pattern (Bad)

Below is a "visually identical" thread list built with <div> and onclick only.It works with a mouse but is completely inoperable via keyboard.Try pressing Tab and arrow keys to feel the difference from the demo above.

<!-- ❌ Anti-pattern -->
<div class="grid">
  <div class="head">From / Subject / Date</div>
  <!-- div elements can't receive focus, and have no row/cell/expand semantics -->
  <div class="row" onclick="toggle('thread')">
    Yamada | Year-end party (3 messages) | 12/10 +
  </div>
  <div id="thread" style="display:none">
    <div class="row">Yamada | Re: Scheduling discussion | 12/10</div>
    <div class="row">Sato | Re: Restaurant booked | 12/11</div>
  </div>
</div>

Implementation Checklist

• The outer container has role="treegrid" and aria-label (name)
• Rows use role="row"; cells use role="gridcell" / role="columnheader"
• Expandable parent rows have aria-expanded that always matches their open/closed state
• Collapsed child rows are hidden from keyboard and screen readers
• Only one tab stop inside the grid; Up/Down arrows move between rows (roving tabindex)
• Right arrow expands (if expanded, moves to the first cell); Left arrow collapses (on a cell, moves left or to the row)
• (Optional) Home / End move to the first and last rows
• (Optional) aria-level / aria-posinset / aria-setsize convey hierarchy and position
• Operable by keyboard alone with visible focus (focus ring is not removed)

Source (English):Treegrid Pattern — W3C APG(opens in a new tab)