275 words
1 minute
A Puzzling Next.js Hydration Error in Safari

The Problem#

While developing with Next.js (v15.1.7), I hit a hydration error using the ListBox component from the HeroUI component library.

Everything worked fine in Chromium-based browsers at first. But when I switched the developer tools to a mobile device profile (iPhone series), the component still worked — except the console now reported a hydration error. My first reaction was that the mobile code path was broken. After digging in, it turned out not to be the code at all: Next.js renders certain tag nestings differently in Safari, and that’s what tripped hydration.

Hydration error in the console

Tracking It Down#

The investigation pointed at how ListBox and ListItem render their tags. ListBox defaults to a ul, and ListItem to an li. That looks perfectly innocent — but something about how Next.js renders these components in Safari causes the hydration error.

Pseudo-code:

Sidebar.tsx
import { Listbox, ListboxItem } from "@heroui/react";
export default function Sidebar() {
return (
<Listbox as="ul">
<ListboxItem as="li" />
</Listbox>
)
}

The Fix#

Try the following tag combinations:

  • ListBox -> ul && ListboxItem -> li
  • ListBox -> ol && ListboxItem -> li
  • ListBox -> div && ListboxItem -> div
  • ListBox -> div && ListboxItem -> p
  • ListBox -> p && ListboxItem -> p

In Chromium-based browsers, only the p-inside-p combination produces a hydration error; every other combination is fine.

In Safari, every single combination produces a hydration error.

So the evidence is clear: something about how Next.js renders these components in Safari is broken. To work around it — using one of the official recommendations for hydration errors — you can render the component dynamically with dynamic and skip Next.js prerendering altogether.

Layout.tsx
import dynamic from "next/dynamic";
const Sidebar = dynamic(() => import("@/components/Sidebar"), { ssr: false });
A Puzzling Next.js Hydration Error in Safari
https://www.mihouo.com/en/posts/front/nextjs-hydration-error-in-safari-browser/
Author
Jia
Published at
2025-03-04
License
CC BY-NC-SA 4.0