Bug: Template HTML element causes hydration issue

[iankduffy]

When using server-side rendering, the template HTML seems to throw a hydration error. Not sure if it's related to how the browser processes template elements or how React is correcting the dom. I have tested this with Astro and Nextjs and have had the same error. The Template element is part of the HTML spec and should work https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/template

Use case might be for shareable web components used in React.

React version: React 19.1, 19.2

Steps To Reproduce

1. Have a component which includes template element with elements inside.
2. Render it server side and wait for hydration error should be triggered

Link to code example:

'use client';
export function Template() {
	return <template>hello</template>;
}

export default function Home() {
	return (
		<main>
			<section className='container mx-auto grid lg:grid-cols-4'>
				<div className='flex flex-col py-8 lg:col-span-3'>
					<Template />
				</div>
			</section>
		</main>
	);
}

The current behavior

Results in Error:

Error: Text content does not match server-rendered HTML.
See more info here: https://nextjs.org/docs/messages/react-hydration-error

Text content did not match. Server: "" Client: "hello"

The expected behavior

Template HTML element is a part of the HTML spec and should not cause hydration errors.

[Mjsadanand]

Looking at this hydration mismatch issue with <template> elements in React SSR, I can see the core problem: React treats <template> content as regular DOM content during hydration, but browsers treat it as inert document fragments.

Root Cause Analysis

1. Server-side: React renders the template content as visible text
2. Client-side: Browser parses <template> content as inert (not part of active DOM)
3. Hydration mismatch: React expects to see "hello" in the DOM, but browser's template content isn't visible in the main DOM tree

Solutions

Solution 1: Use dangerouslySetInnerHTML (Recommended)

'use client';
export function Template() {
  return <template dangerouslySetInnerHTML={{ __html: 'hello' }} />;
}

Solution 2: Use suppressHydrationWarning (Quick Fix)

'use client';
export function Template() {
  return <template suppressHydrationWarning>{'hello'}</template>;
}

Solution 3: Client-side Only Rendering

'use client';
import { useEffect, useState } from 'react';

export function Template() {
  const [isClient, setIsClient] = useState(false);

  useEffect(() => {
    setIsClient(true);
  }, []);

  if (!isClient) {
    return <template />; // Empty server render
  }

  return <template>hello</template>;
}

Solution 4: Use useEffect for Template Content

'use client';
import { useEffect, useRef } from 'react';

export function Template() {
  const templateRef = useRef(null);

  useEffect(() => {
    if (templateRef.current) {
      templateRef.current.innerHTML = 'hello';
    }
  }, []);

  return <template ref={templateRef} />;
}

Best Practice Solution

For web components with templates in React SSR, I recommend this pattern:

'use client';
import { useEffect, useRef } from 'react';

export function WebComponentWithTemplate() {
  const templateRef = useRef(null);

  useEffect(() => {
    // Client-side template content initialization
    if (templateRef.current) {
      // Clear any server-rendered content
      templateRef.current.innerHTML = '';
      
      // Add your template content programmatically
      const content = document.createElement('div');
      content.textContent = 'hello';
      templateRef.current.content.appendChild(content);
    }
  }, []);

  // Server renders empty template, client hydrates properly
  return (
    <div>
      <template ref={templateRef} />
      {/* Other component content */}
    </div>
  );
}

Why This Works

• Server: Renders minimal, predictable HTML
• Client: Uses useEffect to manipulate template content after hydration
• Hydration: No mismatch because server and client initially agree on content
• Web Components: Template content is properly handled as document fragments

Additional Considerations

1. For Astro: Use client directives to control when components hydrate
2. For Next.js: Consider using dynamic imports with ssr: false for template-heavy components
3. Progressive Enhancement: Ensure core content works without JavaScript when using templates

The dangerouslySetInnerHTML approach is usually the cleanest for simple cases, while the useEffect pattern gives you more control for complex web component scenarios.

[iankduffy]

This doesn't feel like the right decision, the template element is a standard HTML, so react shouldn't throw errors at this.