Tuesday, July 29, 2014

HTML Imports: Import HTML Files Into Another HTML Files

HTML Imports

Most of us are familiar with <script src> which we use in loading JavaScript, <link rel="stylesheet"> for CSS, <img> for images, <video> for videos, and <audio> for audios. But we don't have a more declarative way to load HTML. Whilst It's possible to load HTML with iframes element or the JavaScript method XMLHttpRequest(). HTML imports provide a much cleaner way to load self-contained components into web pages.

HTML Import is an exciting new HTML5 feature that allow us to include an HTML file into another HTML file. You're not limited to markup either. An import can also include CSS, JavaScript, or anything else an .html file can contain.

The Markup

The <link> tag is a blessing. We can easily embed stylesheets and JavaScripts needed in multiple documents with it. But instead of using rel="stylesheet", we add the <link> tag, then we add the value import to the rel attribute. Using href we attach the URL of the HTML file.

<link rel="import" href="external.html"/>

With that line of code, you can load the whole world if it happens to be wrapped-up in an HTML file. Should the file to be imported contain further style or script elements, these will be imported as well.

Note: If you wish to import an HTML document from an external domain, you need to make sure It's CORS-enabled.

Accessing Contents of the Import File

HTML imports doesn't work like PHP #includes. The imported HTML file is loaded by the browser and stored behind the scenes. You can then add the contents of the import document to your web page using JavaScript.

Note: This rule only applies to HTML content. Any CSS or JavaScript code will be loaded by the browser and applied to the main document automatically.

var getImport = document.quearySelector('link[rel=import]');

The above code will select all link tags with the rel="import" attribute. There might be a situation whereby you have multiple imported HTML files in your head section and you want to select a specific link tag, you will need to give that link tag an id. Below is an example:

<link rel="import" href="external.html" id="external-file">

Here we've added a simple <link> element to the <head> of our main document that references the HTML file (external.html). We've also added an id to the tag that will help us to reference the element using JavaScript.

Now we can access the specific link tag by passing in the id we gave the imported file.

var getImport = document.querySelector('#external-file');

Further example

Let's say we are importing form.html and it contains:

<div class="valid">
h3 {
color : green;
<h3> Welcome! </h3>
<p> Thank you. </p>

<div class="invalid">
h3 {
color : red;

<h3> Error! </h3>
<p> You have entered an invalid data, please try again. </p>

Note: <style> don't need to be added explicitly. This is a major difference between HTML Imports and <iframe>.

After the file is selected, we can grab a specific portion of the document. We can select content with class valid, like so:

var el = content.querySelector( '.valid' );

Now we can append the content within the body using the JavaScript appendChild() method.

document.body.appendChild(el.cloneNode( true));

The boolean parameter (set here to true) specifies that the browser should also clone any descendent nodes within the contents.

Browser support

At the time of writing this post, this feature works only in Chrome and you will need to enable it manually - go to the chrome://flags page, enable the Enable HTML Imports option, then restart Chrome.

You can check to see if the user's browser supports HTML imports by looking for the import property on the <link> element.

function supportsImports() {
    return 'import' in document.createElement('link');

if (supportsImports()) {
    // HTML imports are supported!
} else {
    // HTML imports are not supported.

Other browsers can make use of a polyfill, which emulates HTML Imports in unsupported browsers.

That's it! You now know how to use HTML imports and templates to create dynamic web pages.