Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

React warning: <th> cannot appear as a child of <thead>

ErrorWarning: validateDOMNesting(...): <th> cannot appear as a child of <thead>.

Short answer

HTML only allows tr elements inside thead. A th must sit inside a tr, so React warns when header cells are placed straight in thead. Wrap the cells in a tr, and check that components rendering th are mounted inside a tr and not directly in thead.

  • Applies to React 19, any browser
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the component file the warning names and look at what sits directly inside <thead>.

    grep -rn -A4 "<thead" src
  2. 2Match what you see, then jump to its fix

    1. 1The path in the message ends in thead > th.th cells are written directly inside theadFix
    2. 2The markup in the file looks fine, but the warning remains; the component is the culprit.A header component returns th cells and is mounted inside theadFix
    3. 3The path in the message ends in tbody > th or table > th.th is placed directly in tbody or tableFix

What does the error look like?

  • Warning: validateDOMNesting(...): <th> cannot appear as a child of <thead>.
  • <th> cannot appear as a child of <thead>. See (unknown) > thead > th

Cause 1 of 3

th cells are written directly inside thead

1Check

The HTML standard says thead holds zero or more tr elements, and th is allowed only as a child of tr.

grep -rn -A3 "<thead>" src | grep "<th"

2Fix

Add one tr inside thead and move the header cells into it.

<table>
  <thead>
    <tr>
      <th scope="col">Name</th>
      <th scope="col">Email</th>
    </tr>
  </thead>
</table>

3Verify

Reload and confirm the warning is gone from the console.

npm run dev

Confirmed by html.spec.whatwg.org

Did this fix it?

Cause 2 of 3

A header component returns th cells and is mounted inside thead

1Check

A component such as <HeaderCells /> renders only th elements. If it is placed in thead with no tr around it, the final DOM breaks the thead content rule.

grep -rn "<th" src --include=*.jsx --include=*.tsx -l

2Fix

Put the tr either in the component or around it, never in neither.

function HeaderRow({ columns }) {
  return (
    <tr>
      {columns.map((c) => <th key={c.id} scope="col">{c.label}</th>)}
    </tr>
  );
}

<thead><HeaderRow columns={columns} /></thead>

3Verify

Check the rendered table in the browser's Elements panel: thead > tr > th.

# open DevTools > Elements and expand thead

Confirmed by developer.mozilla.org

Did this fix it?

Cause 3 of 3

th is placed directly in tbody or table

1Check

Row headers also belong in a tr. A tr sits in thead, tbody or tfoot, and th and td sit only in a tr.

grep -rn -A3 "<tbody" src | grep "<th"

2Fix

Wrap each row's cells, including a row header th, in a tr.

<tbody>
  <tr>
    <th scope="row">Donuts</th>
    <td>3,000</td>
  </tr>
</tbody>

3Verify

Reload and confirm the console is clean.

npm run dev

Confirmed by html.spec.whatwg.org

Did this fix it?

How do I stop it coming back?

  • Keep table structure as table > thead/tbody > tr > th/td, and name table components the same way.
  • Let components that return th or td cells also return the tr, or document that they must be wrapped.
  • Treat console warnings from validateDOMNesting as bugs.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.