https://github.com/webcomponents/html-imports
HTML Imports polyfill
https://github.com/webcomponents/html-imports
Last synced: 8 months ago
JSON representation
HTML Imports polyfill
- Host: GitHub
- URL: https://github.com/webcomponents/html-imports
- Owner: webcomponents
- License: other
- Archived: true
- Created: 2016-12-13T22:00:32.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2020-10-28T16:03:39.000Z (over 5 years ago)
- Last Synced: 2025-01-26T08:31:57.786Z (over 1 year ago)
- Language: HTML
- Homepage: https://www.w3.org/TR/html-imports/
- Size: 1000 KB
- Stars: 74
- Watchers: 12
- Forks: 32
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
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/).
[](https://travis-ci.org/webcomponents/html-imports)
The polyfill hosts the imported documents in the import link element. E.g.
```html
```
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 `` that imported an element.
## Caveats / Limitations
### `.import` is not a `Document`
The polyfill appends the imported contents to the `` 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 `` 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 `` and within other imports; it won't detect imports appended in ``.
If you require to append imports in ``, notify the polyfill of these additions using the method `HTMLImports.loadImports(document.body)`.
### Imported stylesheets in IE/Edge
In IE/Edge, appending `` in a node that is not `` breaks the cascading order; the polyfill checks if an import contains a ``, and moves all the imported `` and `` 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 };
```
And is imported in index.html:
```html
```
This is how the resolved import will look like:
```html
.blue { color: blue };
```
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
```