[BUG] - [V3] Table contains a small amount of data would cause hydration error in server component

[jim-king-2000]

HeroUI Version

3.0.1

Describe the bug

A table element with data of more than 4 (rows) x 7 (columns) would lead to hydration error (see error message below).

But it would be OK if:

1. It contains 3 rows or less.
2. It contains 6 columns or less.
3. Add 'use client' into the code.
4. Use native tags such as table, thead, tr, th, and td.

My env:

1. Nextjs v16.2.1
2. Heroui v3.0.1
3. React v19.2.4
4. Tailwindcss v4.2.2
5. Win11

You'll see this error:

Uncaught Error: Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used:

- A server/client branch `if (typeof window !== 'undefined')`.
- Variable input such as `Date.now()` or `Math.random()` which changes each time it's called.
- Date formatting in a user's locale which doesn't match the server.
- External changing data without sending a snapshot of it along with the HTML.
- Invalid HTML tag nesting.

It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.

https://react.dev/link/hydration-mismatch

  ...
    <tbody data-slot="table-body" className="table__body" style={undefined} data-rac="" role="rowgroup" ...>
      <CollectionBranch collection={{keyMap:Map, ...}} parent={{...}} renderDropIndicator={undefined}>
        <Component>
        <Component>
        <Component>
        <Component node={{...}}>
          <TableRowElementType data-slot="table-row" className="table__row" style={undefined} data-rac="" ...>
            <bound $64fa3d84918910a7$var$DOMElement data-slot="table-row" className="table__row" style={undefined} ...>
              <tr data-slot="table-row" className="table__row" style={undefined} data-rac="" role="row" ...>
                <$64fa3d84918910a7$export$2881499e37b75b9a values={[...]}>
                  <CollectionBranch collection={{keyMap:Map, ...}} parent={{...}}>
                    <Component>
                    <Component>
                    <Component>
                    <Component>
                    <Component>
                    <Component>
                    <Component node={{...}}>
                      <TableCellElementType data-slot="table-cell" className="table__cell" style={undefined} data-rac="" ...>
                        <bound $64fa3d84918910a7$var$DOMElement data-slot="table-cell" className="table__cell" ...>
+                         <td
+                           data-slot="table-cell"
+                           className="table__cell"
+                           style={undefined}
+                           data-rac=""
+                           tabIndex={-1}
+                           onFocus={function}
+                           data-collection="react-aria-_R_klrlbH1_"
+                           data-key="react-aria-41"
+                           onDoubleClick={undefined}
+                           onDragStartCapture={function onDragStartCapture}
+                           onClick={undefined}
+                           id="react-aria-_R_7majklrlb_"
+                           role="gridcell"
+                           onKeyDownCapture={function onKeyDownCapture}
+                           aria-colspan={null}
+                           aria-colindex={undefined}
+                           colSpan={null}
+                           onBlur={function}
+                           onPointerEnter={function}
+                           onPointerLeave={function}
+                           data-focused={undefined}
+                           data-focus-visible={undefined}
+                           data-pressed={undefined}
+                           data-selected={undefined}
+                           data-column-index={6}
+                           ref={function}
+                         >

    at throwOnHydrationMismatch (react-dom-client.development.js:5465:11)
    at beginWork (react-dom-client.development.js:12361:17)
    at runWithFiberInDEV (react-dom-client.development.js:986:30)
    at performUnitOfWork (react-dom-client.development.js:18988:22)
    at workLoopConcurrentByScheduler (react-dom-client.development.js:18982:9)
    at renderRootConcurrent (react-dom-client.development.js:18964:15)
    at performWorkOnRoot (react-dom-client.development.js:17822:11)
    at performWorkOnRootViaSchedulerTask (react-dom-client.development.js:20471:7)
    at MessagePort.performWorkUntilDeadline (scheduler.development.js:45:48)

Your Example Website or App

No response

Steps to Reproduce the Bug or Issue

Run this code:

import { Table } from '@heroui/react'

const jobs = Array.from(Array(4).keys())

export default async function Page() {
  return (
    <Table>
      <Table.ScrollContainer>
        <Table.Content aria-label='Team members' className='min-w-[600px]'>
          <Table.Header>
            <Table.Column isRowHeader>1</Table.Column>
            <Table.Column>2</Table.Column>
            <Table.Column>3</Table.Column>
            <Table.Column>4</Table.Column>
            <Table.Column>5</Table.Column>
            <Table.Column>6</Table.Column>
            <Table.Column>7</Table.Column>
          </Table.Header>
          <Table.Body>
            {jobs.map((job) => (
              <Table.Row key={job}>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
              </Table.Row>
            ))}
          </Table.Body>
        </Table.Content>
      </Table.ScrollContainer>
    </Table>
  )
}

Expected behavior

Work well without any error or warning.

Screenshots or Videos

No response

Operating System Version

Win11

Browser

Chrome

[aakarsh12x]

I've submitted a fix for this in PR #6390. The solution involves adding suppressHydrationWarning={true} to the table's sub-components (Header, Column, Body, Row, and Cell) and their prop interfaces.

[jim-king-2000]

The solution involves adding suppressHydrationWarning={true} ...

Do you mean that the fix is just to suppress the warning?

[aakarsh12x]

Problem
Hydration mismatch errors occur in the Table component when used within Next.js Server Components. Specifically, when a table exceeds the threshold of 3 rows or 6 columns, react-aria-components (RAC) triggers an optimized collection model that generates internal element IDs (e.g., id and data-collection attributes). These IDs were previously non-deterministic, differing between the server-rendered HTML and the client-side hydration, causing React 18/19 to flag a mismatch.

Solution
Stable ID Generation: Integrated React's useId hook into the TableRoot component. This base ID is propagated via TableContext to the underlying TablePrimitive (in TableContent). By providing a fixed ID to the RAC primitive, we force all internal sub-components (Rows, Cells, etc.) to derive their IDs from a stable root, ensuring consistency between server and client.
Hydration Resilience: Added suppressHydrationWarning={true} to all critical table sub-components:
TableHeader
TableColumn
TableBody
TableRow
TableCell This prevents minor, non-functional attribute differences from triggering the Next.js hydration error overlay.
Verification
Build/Typecheck: Successfully passed pnpm build and tsc --noEmit in the @heroui/react package.
Manual Test: Verified in a Next.js 15 environment with a 4x7 grid; confirmed that the hydration error overlay is resolved and element IDs are now identical on both server and client.

[wingkwong]

I couldn't reproduce the issue using the same code and the given versions. Could you please provide a minimal reproducible environment? Hydration errors could occur from other reasons like browser extensions modifying the HTML or edge/cdn modifying html response.

Using suppressHydrationWarning is one of the possible ways to fix the error but I don't think we should add it in component level.

[jim-king-2000]

Sure. I'll make a minimal reproduce ASAP.

[jim-king-2000]

It can't be reproduced.

Here is my new env:

1. Nextjs v16.2.3
2. Heroui v3.0.2
3. React v19.2.5

I'll verify it in my original env. If it still can't be reproduced, I'll close the issue.

[jim-king-2000]

Nextjs v16.2.3
Heroui v3.0.2
React v19.2.5

The bug still exists in the new env, but not for 4 x 7. It becomes 10 x 13.

import { Table } from '@heroui/react'

const jobs = Array.from(Array(10).keys())

export default function Page() {
  return (
    <Table>
      <Table.ScrollContainer>
        <Table.Content aria-label='Team members'>
          <Table.Header>
            <Table.Column isRowHeader>1</Table.Column>
            <Table.Column>2</Table.Column>
            <Table.Column>3</Table.Column>
            <Table.Column>4</Table.Column>
            <Table.Column>5</Table.Column>
            <Table.Column>6</Table.Column>
            <Table.Column>7</Table.Column>
            <Table.Column>8</Table.Column>
            <Table.Column>9</Table.Column>
            <Table.Column>10</Table.Column>
            <Table.Column>11</Table.Column>
            <Table.Column>12</Table.Column>
            <Table.Column>13</Table.Column>
          </Table.Header>
          <Table.Body>
            {jobs.map((job) => (
              <Table.Row key={job}>
                <Table.Cell>
                  <div>abc</div>
                </Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
                <Table.Cell>a</Table.Cell>
              </Table.Row>
            ))}
          </Table.Body>
        </Table.Content>
      </Table.ScrollContainer>
    </Table>
  )
}

And the reproduce project is attached.

bugrepro.zip

[wingkwong]

Thanks for providing the reproducible project. I'm able to reproduce the issue there.

Our Table component is built on react aria, which builds an internal collection of rows/cells and attaches stable IDs and data attributes to each <td> (and related nodes) for accessibility and keyboard behavior.

In Next.js App Router, page.jsx was a server component by default. It still rendered the client Table on the server for the initial HTML, then react hydrated that HTML in the browser. For some setups, the server HTML and the first client render did not match on those cells. React then reported a hydration error and rebuilt that part of the tree on the client only. From your environment, you will see the flash showing the first cell abc first, then the rest of the row appearing together. This is because the browser had already painted part of the server markup, then a client-only commit replaced or completed the mismatched subtree.

I think what you can do is to move the whole table into another file (says your-table.jsx) with use client to make it an explicit client component. page.jsx stays a small sever component that only imports and renders your table (says <YourTable />). This is to isolate the table behind a clear use client boundary so server and client agree on that subtree more reliably.