What are HTML Imports and How Do They Work?

• 4 minutes READ

Have you ever noticed that including another HTML page inside another is like a foreign concept? It’s something that should be easy to do but you don’t see it often. It’s not impossible but tricky. However, HTML imports makes placing documents into HTML pages such as other HTML pages, CSS files and JavaScript files a manageable task.

Introducing HTML Imports

HTML imports is an easy concept to grasp; it is a way to insert other HTML pages into an HTML page. You’d think that this is not that a big deal but it is; you couldn’t do that with ease before.

The funny thing is, HTML is a basic file yet it did in fact require the most effort to work with sometimes. Even PHP files had the capability of includes, why not HTML? Thanks to web components we can now include HTML documents in other HTML documents; you can also load other CSS and JavaScript files with the tag as well. (Life just go that much more awesome.)

Work Around Tricks

Some previously common options included using an iFrame; which are load-heavy elements within the HTML page inside a separate window on the page. It’s kind of out of context and they weren’t the best when it comes to manipulation and display. iFrames can be fascinatingly frustrating to work with. The second most popular option was AJAX, where you preloaded the page through JavaScript and embedded the content. This is a very inconvenient and tedious way to embed content actually.

Getting started

Basic Syntax

Before we go over the examples, let’s briefly go over the syntax of loading a file through the HTML import tag. Imports are a new type of link tag so it should be easy to understand with the following line of code:

<link rel="import" href="/folder/page.html">

They are placed in the header like you’d like a JavaScript or a CSS file.

No-Code Email Template Builder

With Postcards Email Builder you can create and edit email templates online without any coding skills! Includes more than 100 components to help you create custom emails templates faster than ever before.

Free Email BuilderFree Email Templates

Basic Example

In order for the imports to work, you need to have all the pages in question set up on a local server. Now, let’s get started with index.html. Here is a basic HTML page with a basic import:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>What are HTML imports and how do they work</title>
    <link rel="import" href="/intro.html">
  </head>
  <body>
    <h1>Hello from Designmodo</h1>
  </body>
</html>

As you can see, I wasn’t lying about the simplicity; it’s just like calling a stylesheet or a JavaScript file.

Inside intro.html

So what’s inside this imported HTML page?

<div id="intro-dm">
  <h2>We're an awesome blog about web design</h2>
  <p>Designmodo is a great resource of informative material for designers and web developers. We are makers of highly-rated User Interface Packs, you can get acquainted with Designmodo shop here, and you can download a couple of other ui packs for free.</p>
</div>

It’s just a div with some text in it. No need for body or head or any of that. (Talk about simple!)

Appending Imported HTML

In order for imported HTML to show up we do need to use some JavaScript. The code is below. Place it in your original HTML file — for us index.html — and place it in the markup where you’d like the imported file to appear. In this example, it’s after ‘Hello from Designmodo.’

In the snippet, we query the content and add it into a variable. Next, we just append what the variable holds into the HTML.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>What are HTML imports and how do they work</title>
    <link rel="import" href="/intro.html">
  </head>
  <body>
    <h1>Hello from Designmodo</h1>

    <script>
      var link = document.querySelector('link[rel=import]');
      var content = link.import.querySelector('#intro-dm');
      document.body.appendChild(content.cloneNode(true));
    </script>

  </body>
</html>

Low-Code Website Builders

With Startup App and Slides App you can build unlimited websites using the online website editor which includes ready-made designed and coded elements, templates and themes.

Try Startup App Try Slides AppOther Products

Taking It To the Next Level

Have you heard of the scoped attribute in CSS? The scoped attribute let you use a <style> tag inside of an element. The awesome part is that it only affects that element, not the rest of the document as long as the <style> tag is accompanied by “scoped.” Let’s see how the scoped attribute can help us with the imported HTML file.

Add an h1 into the imported document so we can see the difference between the imported HTML’s CSS and index.html. Second, add style to the elements within the imported HTML document. As you can see <style scoped> is literally within the HTML markup not in the head. Thanks to scoped, only the h1 within the imported markup should be affected.

<div id="intro-dm">
  <style scoped>
    h1{ color: red; }
    p{ color: blue; }
  </style>
  <h1>About us<h1>
  <h2>We're an awesome blog about web design</h2>
  <p>Designmodo is a great resource of informative material for designers and web developers. We are makers of highly-rated User Interface Packs, you can get acquainted with Designmodo shop here, and you can download a couple of other ui packs for free.</p>
</div>

If you want to read up some more on the scoped attribute checkout what W3C has to say.

It’s Kind of Like Bootstrap

The way Bootstrap works is you have a bunch of individual files such as bootstrap.css, boostrap.js, and so on. In order to use plugins, you use jQuery; Bootstrap provides markup examples for you. It’s very flexible and easy to manage. The thinking behind Bootstrap was that you would only use the files your project needs. Now, most people download all of it at once, and that’s okay too. The thinking behind HTML imports is similar where you only load files that you need when you need them. This type of logic is becoming more popular as it makes load times faster and organization easier.

Conclusion

Thanks to HTML imports, you can bundle other HTML files as well as CSS and JavaScript files into single resources. This is actually a pretty big deal. Embedding HTML files inside one another was not that easy to do, until HTML imports came around. We are now able to create reusable content that others can bring into their projects thanks to simple line of code. That is powerful — and that is a big deal!

Paula Borowska

Paula Borowska is an innovative and insightful Senior UX Designer at CVS Health, known for her relentless pursuit of designing the best user experiences. As an expert in design systems, user testing, accessibility, and cross-team collaboration, Paula is dedicated to enhancing digital experiences for all users.

Posts by Paula Borowska