An Introduction to HTML Imports

HTML imports are an experimental but promising way of embedding content. Imports are used to embed one HTML document into another; when you think about it this should not be something too difficult, but it currently is. Just like the name of this post suggest, I will give you an introduction to HTML imports by learning how they work and what exactly do they do.

What’s the Point of HTML Imports?

If you want to include an HTML page within another you have to use either an iFrame, AJAX or some other weirder JavaScript based work out. Now, HTML imports are so new that it’s only supported by Chrome. However, they are a very good technological leap forward as they very much simplify the current process of embedding content. The better benefit of HTML imports is that they are not only limited to importing HTML pages but CSS and JavaScript too. You see iFrames are heavy, challenging and inflexible while AJAX is complicated. HTML imports would be an easier, simpler and therefore better way to do so once browsers start to support it.

Enabling HTML imports

The very big downside of HTML imports is that they are not widely supported, yet. Google Chrome 31 does, in fact, currently support it. Of course, you need to manually enable it by going to chrome://flags, finding HTML imports and clicking enable. Once that is done, you’ll have to make sure to restart your browser for the change to take effect.

Using Imports Within a Web Page

First and foremost, make sure you have a standard HTML document. Below you can see the plain website text I will be starting out with.

< !DOCTYPE html>

      Introducing HMTL imports

Demoing HTML imports

That’s a bare HTML document if I’ve ever seen one. The way HTML imports works is by linking one page within another. You can imagine that we will be adding the import within the head, where every other linked page is held. HTML imports are called through a link that then references a specific file – the file you wish to embed.

In order to do this, you will need the <link /> element. Within, you must specify the rel to be import. This set up the relationship of the link to be an import; I’d like to think this is obvious. No? Lastly you have to specify the path to the file you wish to include. Voila, you are on you way to setting up an imported file!


The Imported HTML page

I also have a second page called myPage.html; that’s the one which will be embedded. There is not much within it, see for yourself.

Hello from Web Design Views

Here's a little bit about us

We aim to create a site where anyone interested in these topics can come and solve their problems and learn more on a specific subject.

To keep this introduction simple you can clearly see there is not that much in the file I will be importing. But you can also see that all the file is made up of is a div with a couple of headings and a paragraph. The file lacks a typical HTML structure with document declaration, a head or a body. That’s on purpose. The imported HTML file doesn’t need to have all that jazz because once it will be rendered it will simply be pasted into the original HTML – the one which is using the imported file. Therefore, the mark up would be duplicated so only put in it the HTML you want to see.

Actually Importing an HTML Page

Now that we have our two pages ready to go we can import myPage.html into our index.html page. In order to do this we do need some JavaScript. You’ll need to place <script></script> tags within the HTML mark up on index.html wherever you’d like the imported content to appear. For us, it will be right under the


< !DOCTYPE html>

      Introducing HMTL imports

Demoing HTML imports

Within the <script></script> tags there will be three lines of code that you’ll also need in order for the import to take place. First, we are going to define a new variable that will query the import. It initiates the import, if you will, from that specific file. Then you will also set another variable that will fetch the content you want from the imported file, myPage.html. This will give us access to content from the text ID as we are trying to import everything within it.

The last line of code will take the newly gathered content and append it, or add it, to the page. That’s why the script tag and its content need to be within the HTML mark up and wherever you want the imported content to be pasted. The append function will paste the content right there and then. You can of course play around with the JavaScript to import the text wherever you want but I’m going to stick with this syntax for this example.

Importing an Import

With that all said and explained, did you know you can include an import within your import? I’m not saying that is something you should do. However, that is something you could do if you wanted to create something extra complicated within your website. Actually, I don’t recommend this at all but I thought to throw this out here because that is pretty cool.

Usability Caution

The sequence in which imports are called is actually quiet smart. The way the variables are defined and called means that the event handlers are going to be called before loading the import on the page. Because this uses variables, there won’t be any errors or issues if there is nothing for the handlers to call – which is actually a good thing. There is, of course, still a down side which is that your website may look awkward with the content missing.

Just like with iFrames of AJAX, HTML imports won’t solve the issue of missing content. However, the way the website will handle what happened when the content is unavailable is improved. When there is nothing within an iFrame you know that something is missing, that something went wrong because it usually gives you an error. However, with HTML imports, like I said before, the content simply won’t show up. There wont be any weird behavior or errors on a page to indicate otherwise.


HTML imports give us the ability to package HTML, CSS and JavaScript snippets, share them and reuse them. The ability to do so will change how we use front-end code, as it’s not so easy to do right now. Our lives as developers will not only get easier but it will influence how we code too.

This is a topic that everyone should be excited about as it’s an incredible improvement. So let me know your thoughts, are you in fact excited about this and the effect it will have on the industry?