Fixing HTML Errors in React and Next.js

Why React output fails validation

React builds pages from components, and each component only knows about its own markup. A Card component does not know it has been placed inside a <p>; a Button does not know it is inside a link. Each piece is valid on its own, and the combination is not. Because JSX is compiled to JavaScript function calls rather than parsed as HTML, nothing stops you writing the invalid combination.

What happens next depends on how the page is rendered:

• Client-side only, for example a Vite single-page app: React creates DOM nodes directly with JavaScript, so the browser's HTML parser never sees the invalid nesting. The structure is exactly what you wrote, invalid or not. The checker only sees it if you validate the rendered page.
• Server-rendered, as with Next.js, Remix or React Router framework mode: React produces an HTML string on the server. The browser parses that string with the normal HTML rules and repairs anything invalid. When React then hydrates, it walks the repaired tree expecting its own structure, finds something different and reports a hydration error.

That second case is the important one. Many hydration errors that look mysterious are simply invalid HTML nesting. React's own console message now says as much, with warnings such as In HTML, <div> cannot be a descendant of <p>. This will cause a hydration error. Earlier versions printed a validateDOMNesting warning for the same thing.

The invalid patterns React makes easy

Clickable cards done validly

// One link covers the card; the second link stays a sibling, not a child
export function ArticleCard({ post }) {
  return (
    <article className="card">
      <h3>
        <Link href={`/journal/${post.slug}`} className="card-link">{post.title}</Link>
      </h3>
      <p>{post.excerpt}</p>
      <Link href={`/authors/${post.author.slug}`} className="card-author">{post.author.name}</Link>
    </article>
  );
}
/* CSS: .card { position: relative } .card-link::after { content: ""; position: absolute; inset: 0 }
   .card-author { position: relative; z-index: 1 } */

Next.js specifics

Link and nested anchors

Since Next.js 13, the Link component renders its own <a>. Older code that wrapped an <a> inside Link now errors unless the legacyBehavior prop is set, and code that works around this by putting a link-rendering component inside Link produces an anchor inside an anchor. Pass className and other attributes to Link directly and remove the inner anchor.

The root layout owns html and body

In the App Router, the root app/layout file must render the <html> and <body> elements. That is where the lang attribute goes. Nested layouts must not render them again, or the output contains a second html element.

// app/layout.tsx
export const metadata = {
  title: { default: 'Larchfield Timber', template: '%s | Larchfield Timber' },
  description: 'Garden rooms and summerhouses built to order.',
};

export default function RootLayout({ children }) {
  return (
    <html lang="en-GB">
      <body>{children}</body>
    </html>
  );
}

Metadata and duplicate head tags

Next.js writes the doctype and the charset meta tag for you and builds the rest of the head from the metadata export or generateMetadata. Duplicate or conflicting tags appear when a project also adds its own <head> in a layout, or, in the Pages Router, when several components use next/head for the same tag without a shared key. Pick one mechanism. React 19 can also hoist <title>, <meta> and <link> elements rendered inside components into the head, which is useful but can create duplicates if the framework's metadata does the same job.

Images

next/image requires an alt prop and outputs a valid <img>. Errors usually come from wrapping it in a block element inside a paragraph or button, which is the nesting problem again.

Attributes React writes into the HTML

React translates JSX props into HTML attributes, and most translations are automatic: className becomes class, htmlFor becomes for, and tabIndex becomes tabindex. Three kinds of prop cause validation errors.

• Custom props passed through. A styled component or wrapper that spreads all its props onto a DOM element passes along things like isActive or variant. React warns that it does not recognise the prop on a DOM element, and depending on the value it may still write it into the HTML, where the validator reports an attribute that is not allowed. Destructure custom props before spreading, use transient props where your styling library supports them, or rename genuine custom data to data- attributes.
• Booleans in the wrong place. hidden, disabled and required are real boolean attributes; pass true or false and React adds or omits them. ARIA attributes are not booleans; React writes aria-expanded={true} as the string true, which is correct, but aria-expanded={undefined} leaves it out, which may leave a widget without its required state.
• Hard-coded IDs in reused components. A form field component with a fixed id produces duplicates as soon as it appears twice. Generate IDs with the useId hook. The duplicate ID guide covers this in more depth.

HTML from a CMS

Content from a headless CMS often arrives as an HTML string rendered with dangerouslySetInnerHTML. If that string contains paragraphs and your component places it inside a <p>, the output nests paragraphs, the browser splits them, and hydration fails. Render CMS HTML inside a <div>, and sanitise it on the server both for security and to remove broken markup before it reaches the page.

How to validate a React site

You need to check the HTML the browser actually receives, and for client-rendered parts the DOM after scripts run.

1. Server HTML. Run the HTML Checker against the live or staging URL, or fetch the page with curl and save it. For a static export, the built HTML files are ready to validate directly.
2. Rendered DOM. For client-only routes, open the page, then in the developer tools console run copy(document.documentElement.outerHTML) and paste the result into a validator as direct input.
3. Console warnings. Run the app in development mode and click through each page type. React prints nesting and attribute warnings with a component stack showing exactly which component rendered the problem element.

# Validate a Next.js static export in CI
npx next build             # with output: 'export' in next.config
npx html-validate "out/**/*.html"

html-validate also offers matchers for Jest and Vitest, so a component test can render markup to a string and assert that it is valid. That catches a new nesting error in the pull request that introduces it.

The fix, step by step

Edge cases

• Portals. Modals rendered with a portal appear at the end of the body in the DOM, so their markup is validated there, not where the component sits in the React tree. That usually helps validity rather than hurting it.
• Third-party widgets. Chat widgets, review badges and consent banners inject their own markup after load. Errors from them only appear in the rendered DOM and belong to the vendor.
• Streaming and Suspense. With streaming rendering, fallback markup is replaced as data arrives. Validate the finished page as well as the initial response if the two differ significantly.
• Custom elements. Web components used in JSX need a hyphen in their names. Unknown attributes on them are allowed, so the validator is more lenient there.
• SVG in JSX. Attributes such as strokeWidth are converted to stroke-width automatically. Copying raw SVG from a design tool into JSX without converting attributes is a common source of React warnings, not HTML errors.