How to Use the template Element

The HTML template element keeps a reusable piece of markup for later use. The template itself is not displayed. When your code needs it, you clone its contents and add the copy to the page.

In short

A minimal example

<template id="user-card-template">
  <article>
    <h2 data-name></h2>
    <p data-role></p>
  </article>
</template>

<section id="users"></section>

<script>
  const template = document.querySelector('#user-card-template');
  const card = template.content.cloneNode(true);
  card.querySelector('[data-name]').textContent = 'Aki';
  card.querySelector('[data-role]').textContent = 'Designer';
  document.querySelector('#users').append(card);
</script>

First get the template, then make a deep copy of its content. Add text to the copy and append it to the page to display the card.

Where is the template content?

The elements written inside a template are not ordinary child elements of the template node. Read the reusable markup through template.content.

const template = document.querySelector('#user-card-template');

template.childNodes.length;         // 0
template.content.childNodes.length; // 1

const copy = template.content.cloneNode(true);
document.querySelector('#users').append(copy);

Passing true to cloneNode copies descendants such as the heading and paragraph. Appending the fragment adds its elements to the page.

Adding cards with a template

Only the buttons and the empty list are visible at first. The template contents appear when a copy is added.

Putting data into a template

When you insert a username or other external data, use textContent for ordinary text. Putting a string into innerHTML makes it HTML, which can create unintended elements or script-related security problems.

• Give reusable parts meaningful id or data-* hooks.
• Do not create duplicate fixed id values when adding several copies.
• Keep headings, labels, and descriptions in the instantiated DOM when users need them.
• Decide what users should see if the JavaScript that instantiates the template fails.

Template versus a hidden element

An element hidden with display: none still exists as an ordinary DOM subtree, while its rendering and accessibility exposure are changed. A template stores markup for later cloning instead. Use the element that matches whether you need hidden page content or a reusable blueprint.

Declarative Shadow DOM

template also has an advanced use with the shadowrootmode attribute for Declarative Shadow DOM. This brings Shadow DOM boundaries, slots, focus, accessibility, and browser support into the design.

<my-card>
  <template shadowrootmode="open">
    <slot></slot>
  </template>
  Card content
</my-card>

Start with template.content.cloneNode(true) for ordinary reusable markup. Use Atlas when you need the standards and implementation details of Shadow DOM.

Common mistakes

• Expecting a written template to appear on screen automatically.
• Using template.querySelector() as if the template contents were ordinary children.
• Trying to add the same node repeatedly without cloning it.
• Creating duplicate id values and breaking labels or references.
• Assuming that template sanitizes data or makes unsafe HTML safe.

Learn more in Atlas

For Template Contents, DocumentFragment, parser behavior, Declarative Shadow DOM, accessibility, and implementation evidence, see The template Element in Yugien Atlas.