# @webcomponents/html-imports

> HTML Imports polyfill

Latest version **1.3.1** (published 2023-03-30) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install @webcomponents/html-imports
pnpm add @webcomponents/html-imports
yarn add @webcomponents/html-imports
bun add @webcomponents/html-imports
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.1 |
| Published | 2023-03-30 |
| First published | 2017-05-11 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 101.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | The Polymer Project Authors |
| Maintainers | webcomponents-devs, bicknellr, azakus, aomarks |
| Keywords | html-imports, htmlimports, web-components, webcomponents, polyfill, shim |

## Links

- npm: https://www.npmjs.com/package/@webcomponents/html-imports
- Repository: https://github.com/webcomponents/polyfills
- Homepage: https://github.com/webcomponents/polyfills/tree/master/packages/html-imports
- Issues: https://github.com/webcomponents/polyfills/issues?q=is%3Aissue+is%3Aopen+label%3A"Package%3A+html-imports"
- npm.io page: https://npm.io/package/@webcomponents/html-imports

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 1.3.1 (latest) — 2023-03-30
- 1.0.0-rc.6 (rc) — 2017-05-11
- 1.3.0 — 2021-08-02
- 1.2.6 — 2020-10-21
- 1.2.5 — 2020-07-20
- 1.2.4 — 2020-03-16
- 1.2.3 — 2020-02-26
- 1.2.2 — 2019-09-19
- 1.2.1 — 2019-04-09
- 1.2.0 — 2018-06-11
- 1.1.1 — 2018-01-22
- 1.1.0 — 2017-12-19
- 1.0.3 — 2017-09-29
- 1.0.2 — 2017-09-20
- 1.0.1 — 2017-07-14
- … 1 more at https://npm.io/package/@webcomponents/html-imports/versions

## README

# HTMLImports

## This platform feature, and polyfill, is deprecated, please consider using ES Modules instead.

A polyfill for [HTMLImports](https://www.w3.org/TR/html-imports/).

[![Build Status](https://travis-ci.org/webcomponents/html-imports.svg?branch=master)](https://travis-ci.org/webcomponents/html-imports)

The polyfill hosts the imported documents in the import link element. E.g.

```html
<link rel="import" href="my-element.html">

<!-- becomes -->

<link rel="import" href="my-element.html">
  <!-- my-element.html contents -->
</link>
```

The polyfill fires the `HTMLImportsLoaded` event when imports are loaded, and exposes the `HTMLImports.whenReady` method. This api is necessary because unlike the native implementation, script elements do not force imports to resolve. Instead, users should wrap code in either an `HTMLImportsLoaded` handler or after load time in an `HTMLImports.whenReady(callback)` call.

The polyfill provides the `HTMLImports.importForElement()` method which can be used to retrieve the `<link rel=import>` that imported an element.

## Caveats / Limitations

### `<link>.import` is not a `Document`

The polyfill appends the imported contents to the `<link>` itself to leverage the native implementation of [Custom Elements](https://www.w3.org/TR/custom-elements), which expects scripts upgrading the `CustomElementRegistry` to be connected to the main document.

As a consequence, `.ownerDocument` will be the main document, while `.parentNode` of the imported children will be the `<link rel=import>` itself. Consider using `HTMLImports.importForElement()` in these cases. e.g:

```javascript
const ownerDoc = HTMLImports.importForElement(document.currentScript);
let someElement = ownerDoc.querySelector('some-element');
if (ownerDoc !== HTMLImports.importForElement(someElement)) {
  // This element is contained in another import, skip.
  someElement = null;
}
```

If you require document isolation, use [`html-imports#v0`](https://github.com/webcomponents/html-imports/tree/v0).

### Dynamic imports

The polyfill supports dynamically added imports by observing mutations in `<head>` and within other imports; it won't detect imports appended in `<body>`.

If you require to append imports in `<body>`, notify the polyfill of these additions using the method `HTMLImports.loadImports(document.body)`.

### Imported stylesheets in IE/Edge

In IE/Edge, appending `<link rel=stylesheet>` in a node that is not `<head>` breaks the cascading order; the polyfill checks if an import contains a `<link rel=stylesheet>`, and moves all the imported `<link rel=stylesheet>` and `<style>` to `<head>`. It drops a placeholder element in their original place and assigns a reference to the applied element, `placeholder.__appliedElement`. e.g.

`my-element.html` imports a stylesheet and applies a style:

```html
<link rel="stylesheet" href="my-linked-style.css" />
<style>
  .blue {
    color: blue;
  }
</style>
```

And is imported in index.html:

```html
<head>
  <link rel="import" href="my-element.html" />
</head>
```

This is how the resolved import will look like:

```html
<head>
  <link rel="stylesheet" href="my-linked-style.css">
  <style> .blue { color: blue }; </style>
  <link rel="import" href="my-element.html">
    <link type="import-placeholder">
    <style type="import-placeholder"></style>
  </link>
</head>
```

The placeholders contain a reference to the applied element:

```javascript
var myImport = document.head.querySelector('link[rel=import]').import;
var link = myImport.querySelector('link');
console.log(link.__appliedElement || link);
var style = myImport.querySelector('style');
console.log(style.__appliedElement || style);
```

## Building & Running Tests

### Build

```bash
$ git clone https://github.com/webcomponents/html-imports.git
$ cd html-imports
$ npm i
$ bower i
$ gulp
```

### Run tests

```bash
$ npm i -g web-component-tester
$ wct
```

---
_Source: https://npm.io/package/@webcomponents/html-imports · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._