Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


<html-include> is a very simple Web Component for including the raw content of an HTML file.

It's somewhat similar to doing a PHP include for a plain html file (looks familiar? <?php include('header.html'); ?>), but on the browser side.

It looks like this:

<html-include src="header.html"></html-include>

Whatever content you load with it, it will replace the <html-include>'s outerHTML.

This is a vanilla-js component and it has no dependencies.


Check a demo here:


Actually, perhaps you would get better performance by just having everything on your main html and not using this. ;)

Using <html-include> means it will make an extra request for each file it loads.

But, if you are not expecting certain files to change, you can configure your server cache control for those files to improve performance and reduce requests.

If it's an option, try to use server-side includes instead. (For static sites, you could use a preprocessor, like jekyll or harpjs)


You can just copy the dist/html-include.min.js file somewhere onto your server, or you can use bower:

bower install --save html-include


First, make sure you have the webcomponent's polyfill:

  if ('registerElement' in document
    && 'createShadowRoot' in HTMLElement.prototype
    && 'import' in document.createElement('link')
    && 'content' in document.createElement('template')) {
    // We're using a browser with native WC support!
  } else {
    document.write('<script src="https:\/\/"><\/script>')

Then you can choose to either include the HTML, like a regular web component:

<link rel="import" href="html-include.html">

Or actually, you can just include the script:

<script src="html-include.min.js"></script>

(just do one of the two, don't do both)

Do it immediately after the webcomponents polyfill, and before any other scripts. (So it can capture the DOMContentLoaded event)

After that you can use it like this:

<html-include src="header.html"></html-include>

Whatever content header.html has, it will replace the actual html-include tag in the DOM.

If the file in the src can't be read, then it will be replaced by an empty string.

It will load the content using a XMLHttpRequest, and prevent emitting the DOMContentLoaded event (and the window load event) until all the html-include elements (with the src attribute) on the DOM are resolved. At that moment, a DOMContentLoaded event will be emitted, and it will see the fully composed html.


Attribute Options Default Description
src string '' Name of the file to be included.
prevent-cache boolean false Add a random string as query parameter to the src file, to prevent cache.


MIT License


Simple way to include the raw content of an HTML file on your DOM






No packages published