<remote-template> Web Component

A dependency-free Web Component that fetches a URL and appends the response to a <template>.

🐶 🧩 See <remote-template> in action!

Getting <remote-template>

You've got several options for adding this Web Component to your project:

• Download a release from GitHub and do it yourself (old school).
• Install using npm: npm install @jgarber/remote-template --save
• Install using Yarn: yarn add @jgarber/remote-template

Usage

First, add this <script> element to your page which defines the <remote-template> Web Component:

<script type="module" src="remote-template.js"></script>

The <remote-template> Web Component may then be used to append a <template> element loaded from a remote URL:

<remote-template src="/templates/basic.html"></remote-template>

The response text of basic.html is queried for a <template> element. If none is found, this Web Component treats the response text as a "bare" template, wrapping a <template> element around the contents before appending to the DOM.

The following two examples are functionally equivalent:

<template>
  <p>Hello, world!</p>
</template>

<p>Hello, world!</p>

You may also use a fragment identifier to append a specific <template> from a collection of templates embedded in a single HTML file:

<remote-template src="/templates/collection.html#template-2"></remote-template>

The HTML file at /templates/collection.html may contain something like:

<template id="template-1">
  <p>Hello from Template #1!</p>
</template>

<template id="template-2">
  <p>Hello from Template #2!</p>
</template>

[!NOTE] Fragment identifiers can match attributes other than id. For the purposes of this Web Component, fragment identifiers are considered id attribute values.

This Web Component may also be embedded in other Web Components to achieve various effects:

<parent-component>
  <remote-template src="/templates/shared.html"></remote-template>

  <p slot="greeting">Call me Ishmael.</p>
</parent-component>

[!TIP] See the Events documentation below for details on how to respond to events dispatched by the <remote-template> Web Component.

[!IMPORTANT] Unfortunately, this implementation will not work with Declarative Shadow DOM. In that mode, <template> elements must be present in the document when the HTML parser executes.

HTTP Request Headers

When fetching remote templates, this Web Component uses the Fetch API with the following HTTP request header:

Accept: text/template+html, text/html

Note that text/template+html is not an official MIME type. You can just like… make things up. Despite this, its presence may be useful if you configure your application server to respond differently based on this value. Otherwise, plain old semantic HTML works just fine.

Events

The <remote-template> Web Component dispatches a load event after the remote template has been successfully fetched and appended to the DOM. Listening for this event is most useful when embedding a <remote-template> within another Web Component.

connectedCallback() {
  this.addEventListener("load", this);
}

handleEvent(event) {
  if (event.type === "load") {
    const shadow = this.attachShadow({ mode: "open" });
    shadow.append(this.querySelector("template").content.cloneNode(true));
  }
}

An error event may be emitted if the Web Component encounters a problem loading the remote template. In this case, the underyling Error may be accessed by inspecting the event's detail property.

connectedCallback() {
  this.addEventListener("error", this);
}

handleEvent(event) {
  if (event.type === "error") {
    console.error("Error loading remote template:", event.detail.error);
  }
}

License

The <remote-template> Web Component is freely available under the MIT License.