Templating

Markup uses tagged template literals called html to describe the HTML you want to render.

1const temp = html`<h1>Hello World</h1>`

The html returns an HTMLTemplate instance containing methods and properties you can use to access or perform many actions.

Rendering

There are few ways to render a template after you define it:

• render: Takes a HTMLElement to append the template to;
• replace: Takes any Node or another HTMLTemplate instance to replace in the DOM;
• insertAfter: Takes any Node or another HTMLTemplate instance to insert the template after;

render

The render method will take either a ShadowRoot, HTMLElement, or DocumentFragment to append the content to.

1temp.render(document.body)

The parsing of the template happens at render time and will only happen once. This is also true for other rendering methods.

Calling the render method with same target repeatedly will only work once. You can call it with a different target to move content to a different place.

1temp.render(document.body) // will parse and append to document.body2temp.render(document.body) // will be ignored3temp.render(document.body) // will be ignored4temp.render(document.getElementById('app')) // will move content to #app

replace

The replace method takes any HTMLTemplate or Node as long as it is not a ShadowRoot, HTMLBodyElement, HTMLHeadElement, or HTMLHtmlElement to replace in the DOM.

1temp.replace(document.getElementById('app'))

Similar to render method, it will only parse content once.

1const loading = html`<p>loading...</p>`2 3html`${loading}`.render(document.body)4 5doSomethingAsync().then(() => {6    const done = html`<p>Done</p>`7 8    done.replace(loading)9})

The replace method is powerful especially when working with asynchronous rendering you can render something temporarily like a loading indicator and then replace it later once you have your data. This is exactly what suspense utility does.

insertAfter

The insertAfter method works exactly like the render method. The only difference is that it adds the template content after the provided target node.

1temp.insertAfter(document.getElementById('app'))

Another difference is that it can also take a HTMLTemplate instance as target, allowing to render templates one after another.

1const items = [2    html`<li>Buy groceries</li>`,3    html`<li>Go to gym</li>`,4    html`<li>Write a blog</li>`,5]6 7html`<ul>8    ${items}9</ul>`.render(document.body)10 11html`<li>Read a book</li>`.insertAfter(items[1])

parentNode

The parentNode property will tell you where the template was rendered. It will return the element in which the template nodes were added to.

mounted

After you render your template, you can use the mounted property to check if your template was added to the target as you wanted.

The mounted property will not tell you if the template is actually attached to a document. For that, you can use the parentNode?.isConnected.

1const temp1 = html`one`.render(document.createDocumentFragment())2const temp2 = html`two`.render(document.body)3 4console.log(5    temp1.mounted, // true6    temp1.parentNode?.isConnected // false7)8 9console.log(10    temp2.mounted, // true11    temp2.parentNode?.isConnected // true12)

childNodes

The childNodes will give you an array of top level Nodes rendered by the template.

1const temp = html`2    Loose text3    <p>a paragraph</p>4    <button>click me</button>5    ending6`.render(document.body)7 8console.log(temp.childNodes) // [text, p, text, button, text]

unmount

To remove your template from the target, you can use the unmount method.

1temp.unmount()

The unmount should be the ONLY way you go about removing the template from the DOM. This is because it also unsubscribes from any state recursively. This means that even when you nest templates, the unmount will be called for all of them.

Directly manipulating the DOM may have undesired results.

toString

Conveniently, you can get a string representation of your template in its current rendered state.

1const temp = html`2    Loose text3    <p>a paragraph</p>4    <button>click me</button>5    ending6`.render(document.body)7 8console.log(temp.toString())9/* 10Loose text11<p>a paragraph</p>12<button> click me</button>13ending14 */

Livecycles

There are additional methods available for lifecycle purpose. You can learn more by checking the lifecycle document.