Hydration and HTML nesting

The step where server-rendered HTML is adopted by client JavaScript — and the invalid nesting that silently breaks it.

What it is

The server sends HTML; the client renders the same tree and attaches it to the existing DOM. If the two disagree, the server HTML is discarded and the page is re-rendered from scratch.

Why it is needed

A mismatch throws away the work the server did and re-renders everything on every load. The only symptom is a minified error in the console.

How it works

HTML forbids flow content inside a paragraph. When a parser meets a div inside a p it auto-closes the paragraph, so the DOM the browser builds does not match the tree the framework rendered.

At a glance

Allowed inside <p>	Not allowed
span, a, button, code, em, strong	div, section, dialog, h1-h6
img, br, small, abbr	p, ul, ol, li, dl, table, pre, figure

In this project

This project hit exactly that: an inline metric reference rendered its full panel — dialog, section, headings, pre, lists — at the reference point, which sat inside a paragraph of prose. The fix was structural rather than per-tag: the inline trigger returns phrasing content only, and panels render once per page outside the prose tree. A build-time guard now scans the emitted HTML with an explicit element stack and fails the build on flow content inside a paragraph, and it was verified by reintroducing the bug and confirming it caught all four violations.

Trade-offs

Advantages

Server HTML is reused rather than rebuilt
Content is visible before JavaScript loads

Limitations

The server and client trees must agree exactly
Mismatches fail loudly only in development

Common mistakes

Rendering block content at an inline reference point
Testing only in development, where production behaviour differs
Patching individual tags rather than fixing the structure

When to use it

Reach for it when

Any server-rendered framework

How it interacts with the rest of the system

Static export and precomputed interaction

← All topics