<embed-html> The HTML-Embedding Web Component

How to use

  1. Include the JavaScript anywhere on your page:

    <script type="module" src="//embed-html.danq.dev/embed-html.js"></script>

    (or download embed-html.js file and host it yourself)

  2. Use the <embed-html> element to embed other HTML files:

    <embed-html src="embedded-content.html"></embed-html>

    Now the contents of that file get injected into your page!

Example

The HTML below was embedded from embedded-content.html:

Why would I use this?

If you're writing static HTML web pages but you're not using a static site generator, it can be hard to keep shared components like your site header or menu in-sync across all of your pages.

A popular solution is to use an <iframe> element, but this introduces a few challenges. <iframe>s are styled separately from the rest of your page, can introduce challenges for responsive design and accessibility, require their size to be specified independently of their content, and make interactions "between" the iframe and the rest of your page much more difficult.

Another popular solution is to use a shared JavaScript file to render the content. This project is a streamlined version of that approach, implemented as a Web Component.

Advanced usage

Now you know everything you need to use <embed-html>. But there are a few advanced features you might like:

Caching

By default, the content is fetched and injected into the page every time the <embed-html> element is loaded. If you set the cache attribute, the content will be cached in localStorage (with a "refresh-in-background" strategy):

<embed-html src="embedded-content.html" cache></embed-html>

The next time the page is loaded, the embedded page will be loaded from the cache and will appear instantly! The cache will be quietly updated in the background if the embedded page has been changed, and the updated version will be shown the next time the page is loaded.

cache is a great option to use for content that doesn't change very often like headers and menus, especially if they're used across many pages.

Delays and lazy-loading

If you want to reduce the bandwidth consumed by loading your page, or prioritise loading other content first, you can use the lazy and/or delay attributes. This can be helpful for footers of long pages, for example. Note that lazy and delay do nothing if cache is set!

lazy mode makes the embedded content only load once it's scrolled into view:

<embed-html src="embedded-content.html" lazy></embed-html>

delay mode makes the embedded content only load after a time delay (in milliseconds):

<embed-html src="embedded-content.html" delay="1000"></embed-html>

If you use both lazy and delay, the delay timer only starts after the embedding area scrolls into view.

Fallback content

Anything placed within the <embed-html> element will be shown only until the embedded content is loaded. This means it's suitable for things like:

Styling

The <embed-html> element can be styledwith CSS like any other HTML element. Any styles applied to it are thrown away once the embedded content is loaded. This means it can be used to style a "loading" placeholder or other fallback content:

<embed-html
  src="embedded-content.html"
  style="display: grid; place-items: center; background-color: #eee;"
>
  Loading...
</embed-html>

If you can accurately estimate the height that the embedded content will take up, this approach can also be used to "hold" the vertical space in the page (so content doesn't "jump" when it loads):

<embed-html src="embedded-content.html" style="display: block; height: 200px;">
</embed-html>

Nesting

It's possible - though perhaps not advisable! - to nest <embed-html> elements inside embedded content. Just be careful not to create an infinite loop!

Cross-origin embeds

If you want to embed HTML from a different domain (site), you'll need need the other site's webserver to be configured for cross-origin requests or they won't work.