The <template> Element

Technical Summary

Definition / Categories

Item	Definition
Meaning	A declaration of an HTML fragment that can be cloned and inserted into a Document by script
Categories	Metadata content, Flow content, Phrasing content, Script-supporting element
Contexts	Where metadata, phrasing, or script-supporting content is expected; also the special colgroup context without a span attribute
Content model	Nothing. Markup written between the tags becomes Template Contents
Tag omission	Neither the start tag nor the end tag is omissible
Content attributes	Global attributes, for, shadowrootmode, shadowrootdelegatesfocus, shadowrootserializable, shadowrootslotassignment, shadowrootclonable, and shadowrootcustomelementregistry
DOM interface	HTMLTemplateElement; content is a readonly DocumentFragment

Template Contents and the DOM tree

When the HTML parser processes a template, its markup is not treated as ordinary children of the template element. It is placed in the Template Contents returned by template.content.

<template id="card-template">
  <article>
    <h2>Card</h2>
  </article>
</template>

const template = document.querySelector('#card-template');
template.childNodes.length;         // 0
template.content.childNodes.length; // 1
template.content.firstElementChild.nodeName; // "ARTICLE"

This is more than a CSS visibility choice. Template Contents have their own owner-document and insertion processing, so parser behavior, DOM manipulation, adopting, and custom elements must be considered together.

Clone, insert, and ID boundaries

content is a DocumentFragment. Clone it deeply, update references in the clone, and then insert it into the Document. Reusing a template also requires an explicit plan for duplicate IDs, label/for, ARIA references, and form-control names and values.

const template = document.querySelector('#card-template');
const fragment = template.content.cloneNode(true);
const heading = fragment.querySelector('h2');
heading.textContent = 'A cloned card';
document.querySelector('#cards').append(fragment);

Clone as many times as needed rather than trying to insert the same node repeatedly. When external data is not intended to be parsed as HTML, set it with textContent; the template element is not a sanitizer.

Rendering, instantiation, and accessibility

The template element represents nothing in rendering. Its contents are not live page content for users until they are instantiated into the normal Document tree. After insertion, the resulting headings, labels, buttons, form controls, and ARIA relationships become the subjects of ordinary semantic and accessibility evaluation.

Writing meaningful content inside a template therefore does not guarantee that users can reach it. Fallback behavior, focus after insertion, names and roles, and status announcements must be tested separately.

Declarative Shadow DOM

shadowrootmode makes a template participate in Declarative Shadow DOM. open and closed select the shadow-root exposure state, while shadowrootdelegatesfocus, slot assignment, serialization, clonability, and a custom element registry add further conditions.

<my-card>
  <template shadowrootmode="open">
    <style>:host { display: block; }</style>
    <slot></slot>
  </template>
  <span>Light DOM content</span>
</my-card>

Declarative Shadow DOM requires separate treatment of parser-created shadow trees, Template Contents, assigned slot nodes, and host/shadow-tree accessibility boundaries. Results from ordinary cloning must not be generalized to every Declarative Shadow DOM configuration.

The for attribute and streaming use

The HTML Standard defines the template for attribute for inserting or replacing content at a location identified by processing instructions. This is a different processing model from ordinary client-side cloning, so implementation support and conditions must be recorded before relying on it.

Accessibility

Separate the fact that a template represents nothing in rendering from the way instantiated contents appear in an accessibility tree. A template does not automatically provide an accessible name for a heading or control that will eventually be created.

Stage	What to inspect	Boundary
Before instantiation	The template element and Template Contents	Do not treat them as live rendered content or an interaction target
After ordinary insertion	Headings, labels, buttons, form controls, and live regions	Observe semantics, names, and focus on the inserted DOM
Shadow DOM	Host, shadow tree, slots, and focus delegation	Separate browser, platform API, and assistive-technology mappings

Fact / Evidence

Normative claims about the template element, Template Contents, the DOM interface, and Declarative Shadow DOM are separated from browser and accessibility observations.

Evidence

1. HTML Standard: the template element — definition, categories, content attributes, HTMLTemplateElement, and rendering
2. DOM Standard: DocumentFragment — the fragment interface used for Template Contents
3. HTML Accessibility API Mappings — an entry point for separating the template from its instantiated contents
4. Web Platform Tests: the-template-element — tests for template parsing, content, and DOM APIs
5. Web Platform Tests: declarative Shadow DOM — tests related to shadowrootmode and shadow trees

Implementation Evidence

Normative processing is registered separately from browser observations of Template Contents, cloning, parsing, Declarative Shadow DOM, and accessibility trees. No dedicated fixture has been run yet, so unrun items remain unreviewed.

Dedicated fixture candidate: template-v1 should reproduce the difference between child nodes and content, deep cloning, fragment insertion, duplicate IDs, shadowrootmode, and accessibility trees before and after instantiation.

Coverage / Open Issues

• CoveredMeaning, categories, contexts, content model, tag omission, and content attributes
• CoveredTemplate Contents, DocumentFragment, content, and the normative entry points for cloning and insertion
• CoveredNormative entry points for shadowrootmode, slot assignment, focus delegation, and serialization
• OpenCross-browser comparison of parsing, custom elements, adopting, dynamic changes, duplicate IDs, and form/ARIA references
• OpenDeclarative Shadow DOM, slots, closed roots, focus, serialization, and custom element registry implementation differences
• OpenIndividual WPT results, HTML-AAM platform mappings, assistive technology, compatibility, and Expert-gap Review

This page is initial coverage. It organizes normative entry points without claiming identical behavior across browsers, DOM operations, custom elements, Shadow DOM configurations, or assistive technologies.

Related surface

For the beginner-friendly explanation of reusable markup, content, and cloning, see How to Use the template Element in Yugien. DOM operations are also covered by The script Element; slot and shadow-tree behavior remain part of the Declarative Shadow DOM implementation scope.