HTML Imports

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Web Applications Working Group as a Discontinued Draft using the Recommendation track.

Publication as a Discontinued Draft does not imply endorsement by W3C and its Members.

Publication as a Discontinued Draft implies that this document is no longer intended to advance or to be maintained. It is inappropriate to cite this document as other than abandoned work.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 2 November 2021 W3C Process Document.

HTML Imports, or just imports from here on, are HTML documents [HTML] that are linked as external resources from another HTML document. The document that links to an import is called an import referrer. For any given import, an import referrer ancestor is its import referrer or any import referrer ancestor of its import referrer. There are one or more import referrers and import referrer ancestors for each import because same import can be referred from multiple import referrers.

An import referrer that is not an import, thus is not associated with any import referrer, is called a master document. Each import is associated with one master document: if the referrer of the import is a master document, it is the master document of the import. Otherwise, the master document of the import referrer is the master document of the import.

The URL of an import is called the import location.

In each import referrer, an import is represented as a Document [WHATWG-DOM], called the imported document.

Issue 197: [imports]: The relationship between import and browsing context should be stated more clearly (bugzilla: 26682) html-imports needs-clarification

The imported documents don't have browsing context.

The set of all import associated with the master document forms an import map of the master document. The maps stores import as its items with their import locations as keys. The import map is empty at beginning. New items are added to the map as import fetching algorithm specifies.

To track requested imports, each document has an import link list. Each of its item consists of link, a link element and location, a URL. Also, the item is optionally marked as branch. The list is initially empty, and items are added to it as specified by the import request algorithm.

Each imported document has an import parent: If the import link list of document A contains a branch item whose location points document B, A is an import parent of B.

Each imported document also has one or more import ancestors: Document A is an import ancestor of another document B if A is import parent of B. Being an import ancestor is transitive: If A is an import parent of B and B is an import parent of C, A is an import parent of C as well.

An imported document also has one or more import predecessors. An import predecessor is a document. If the URL of document A is located before the URL of document B in the import link list of B's import parent, and the located link is marked as a branch, then A is import predecessor of B.

The import ancestor predecessors of document A is defined as follows: If document B is an import predecessor of document C, and C is an import ancestor of A, B is an import ancestor predecessors of A.

The Document that is in either import ancestor predecessors or import predecessors of document A, or is linked from branch item of A's import link list, is the import dependent of A.

The import link list and the import dependent constrains the order of script execution in imports. It is intend to give a deterministic order of script execution which is defined by the order of link element in each import. The edges of each node is ordered in terms of import link list. The import predecessors selection is aware of the order.

The linking structure of import link lists forms a directed graph. Each node of the graph is a document and its edge is a link. Branches are intended to form a spanning tree of the graph. This tree gives the deterministic order of the script execution.

Figure 1 An example of import link lists

In Figure 1,

The document A has an import link list which contains a link to B and another link to C.
The document D has a couple of import ancestors that are A and B.
As B is a import ancestor of D, one of D's list item that points B is not marked as a branch.
Even though the document D is linked from two documents B and C, its import parent is B because B has a link to D which is marked as a branch.
Look at E:
- E doesn't have any import predecessors. The link to D from C is not marked as branch, and the link to G isn't located before one to E.
- E's import ancestors are A and C.
- E's import ancestor predecessor is B because import predecessors of C is B and A has no import predecessors.
- E's import link list contains H which is marked as a branch.
- Thus E's import dependents are B, an import ancestor predecessor, and H, an item of an import link list.
Look at G:
- G's import predecessors is E.
- G's import ancestor predecessor is same as E's, which is B.
- G's import link list is empty.
- Thus G's import dependents are B, an import ancestor predecessor, and E, an import predecessors.

The difference between the import referrer and the import parent is that import referrer reflects the state of the node tree and that the import parent is built by the algorithm described in this document.

To enable declaring import in HTML, a new link type is added to HTML link types:

The import keyword may be used with link elements. This keyword creates an external resource link to an import.

The default type for resources given by the import keyword is text/html.

The link element may have an async attribute. The async attribute is a boolean attribute.

The appropriate time to fetch the resource is when the external resource link is created or when its element is inserted into a document, whichever happens last.

The import is fetched and applied regardless of the media attribute of the link matches the environment or not.

Example 1

The following document has one import, located at /imports/heart.html:

<!DOCTYPE html>
<html lang="en-US">
    <head>
        <title>Human Being</title>
        <link rel="import" href="/imports/heart.html">
    </head>
    <body>
        <p>What is a body without a heart?</p>
    </body>
</html>

WebIDLpartial interface HTMLLinkElement {
    readonly attribute Document? import;
};

On getting, the import attribute MUST return null, if:

The link does not represent an import
the link element is not in a Document

Otherwise, the attribute MUST return the imported document for the import, represented by the link element.

The same object MUST be returned each time.

Example 2

Here's how one could access the imported document, mentioned in previous example:

var link = document.querySelector('link[rel=import]');
var heart = link.import;
// Access DOM of the document in /imports/heart.html
var pulse = heart.querySelector('div.pulse');

An import in the context of the Document of an HTML parser or XML Parser is said to be an import that is blocking scripts if the element was created by that Document's parser, or and the element is a link of type import when the element was created by the parser, and the link is not marked as async, and the the import is yet to be completely loaded, and, the last time the event loop has reached step 1, the element was in that Document, and the user agent hasn't given up on that import yet. A user agent MAY give up on an import at any time.

Note

Giving up an import before it loads, even if the import eventually does still load, means that the script might end up operating with incorrect information. For example, if an import registers a custom element and a script relies on the availability of this element, the script will find that this element is unavailable if the user agent gives up early. Implementers have to balance the likelihood of a script using incorrect information with the performance impact of doing nothing while waiting for a slow network request to finish.

A Document has an import that is blocking scripts if there is an import that is blocking scripts in the Document's import dependent. A Document has no import that is blocking scripts if it does not have an import that is blocking scripts as defined in the previous paragraph.

Note

The state of "has an import that is blocking scripts" can change each time an existing import is completely loaded or new import loading is started. HTML parser has changes to unblock it for each of such timings.

Add following step as the first step of the definition:

Throws an InvalidStateError exception if the Document is an import.

Add following step as the first step of the definition:

Throws an InvalidStateError exception if the Document is an import.

Add following step as the first step of the definition:

Throws an InvalidStateError exception if the Document is an import.

After a link is added to the import link list, the update marking algorithm MUST be run with the master document. which is equivalent to running these steps:

Input: DOCUMENT, the Document

If the DOCUMENT is the master document, unmark branch of all the links in the import link list of DOCUMENT and every import that is associated to DOCUMENT.
Let LIST be an import link list of DOCUMENT.
For each ITEM in the LIST:
1. Let LOCATION be a location of ITEM.
2. Let IMPORT be an import whose URL is same as LOCATION.
3. If there is no other link whose location is same as LOCATION and which is marked as a branch, mark ITEM as a branch.
4. If ITEM is marked as a branch and IMPORT is not null, invoke update marking algorithm with IMPORT.

When user agents attempt to obtain a linked import, they MUST also run the import request algorithm, which is equivalent to running these steps:

Input: LINK, the link element that creates an external resource link to the import.; LOCATION, the URL of the linked resource.

If the async attribute of LINK is true, mark LINK as async.
Let DOCUMENT be a document of LINK.
Let LIST be an import link list of DOCUMENT.
Let ITEM be LINK and LOCATION:
1. Add ITEM at the end of LIST.
2. Invoke update marking algorithm with the master document.

All import linked from documents that is the master document or the one in the import map MUST be fetched using the import fetching algorithm described below, instead of the one that HTML specifies to obtain a linked resouce.

The import fetching algorithm MUST be equivalent to running these steps:

Input: LINK, a link element which makes the external resource link to the import.; LOCATION, the import location
Output: IMPORT, the imported document.

If LOCATION is already in the import map:
1. Let IMPORT be the imported document for LOCATION and stop.
Fetch a resource [Fetch] from LOCATION with request's origin set to the origin of the master document, the mode to CORS and the credentials mode to same-origin.
1. If fetched response type is error or the response has a header whose name is Content-Disposition:
  - Add LOCATION and null to the import map and stop.
2. Let IMPORT be a new Document, the document's address of which is LOCATION
3. Let PARSER be a new HTML parser, associated with IMPORT
4. Add LOCATION and IMPORT to the import map.
5. For each task that the networking task source places on the task queue while fetching:
  1. Fill PARSER's input byte stream with the fetched bytes
  2. Let PARSER process the input byte stream with utf-8 [WHATWG-ENCODING] as a known definite encoding
6. When no more bytes are available:
  1. Queue a task from the networking task source for PARSER to process implied EOF character

Note

All of loaded imports and imports under loading are in the import link list, thus every import which is linked from imports in the list will also be loaded using the import fetching algorithm, with LOCATION be the import location of the import.

The loading attempt MUST be considered successful if IMPORT is not null on the algorithm completion, and failed otherwise.

Every import that is not marked as async delays the load event in the Document.

Note

The link element fires a simple event called load for successful loading attempt. For failed attempt, it fires a simple event named error.

As an import delays the load event, the Document isn't completely loaded until loading attempts of all of its linked imports are finished.

Content Security Policy [CSP3] MUST restrict import loading through the script-src directive.

Each import MUST be restricted by the Content Security Policy of the master document. For example, if Content Security Header Field is sent to an import, the user agent MUST enforce the policy of the master document to the imported document.

Parsing behaviour of import is defined as a set of changes to the HTML Parsing.

In step 15 of prepare a script algorithm, modify the last part of condition which begins with If element does not have a src attribute to read:

... and the Document of the HTML parser or XML parser that created the script element has a style sheet that is blocking scripts or has an import that is blocking scripts

At the DOCTYPE part of section 12.2.5.4.1 The "initial" insertion mode, modify text if the document is not an iframe srcdoc document... as follows

if the document is not an iframe src document nor an import...

In sub-condition named Otherwise of condition An end tag whose name is "script" in "text" insertion mode, modify step 3 to read:

If the parser's Document has a style sheet that is blocking scripts or has an import that is blocking scripts or the script's "ready to be parser-executed" flag is not set: spin the event loop until the parser's Document has no style sheet that is blocking scripts and has no import that is blocking scripts and the script's "ready to be parser-executed" flag is set.

Modify step 3 of steps that run following preparing the script element to read:

Spin the event loop until the parser's Document has no style sheet that is blocking scripts and has no import that is blocking scripts and the pending parsing-blocking script's "ready to be parser-executed" flag is set.

The contents of the style elements and the external resources of the link elements in import MUST be considered as input sources of the style processing model [CSS2] of the master document.

A set of imports that are associated with a master document forms an import link tree, a tree structure. Following import link tree forming algorithm, being applied with null as PARENT, master document as TREE and all of its imports as POOL, defines the import link tree:

Input: PARENT, a document tree node; CURRENT, a document; POOL, a list of document
Output: TREE, a tree of document

Let TREE be a tree node.
Let TREE's value be CURRENT
Let TREE's parent be PARENT.
Make TREE's child list empty.
For each LINK, a link element of an import in CURRENT, in document order:
1. Let IMPORT be the import of LINK.
2. If IMPORT is not in POOL, try next.
3. Remove LINK from POOL.
4. Invoke the import link tree forming algorithm with TREE as PARENT, IMPORT as CURRENT and POOL as POOL, let the result be CHILD.
5. Append CHILD to TREE's child list.
stop.

Note

The import link tree algorithm defines a order of imports using a depth first traversal. This import link tree is different from the one formed by import link list. The former is based on the document tree of each import. The later is built through import loading process and isn't affected by document tree mutation.

The order of appearances of declarations [CSS-CASCADE-3] which come from different documents are determined by the import link tree. If node documents of two declarations differ, compare the tree order of these documents in the import link tree. The last one wins.

This specification redefines custom element order to be the sum of [CUSTOM-ELEMENTS]'s custom element order and import tree order, in which the import tree order is scaled so that its lowest value is always larger than the highest possible value of [CUSTOM-ELEMENTS]'s custom element order.

The import tree order of a given custom element of an import link tree is determined by tree order in an import link tree that was flattened by replacing every import link with the content of its imported document.

The highest stable order is the value that is immediately preceding the custom element order of an element in the first encountered import, in tree order, that has not yet completely loaded. If there is no such element, the highest stable order is the highest custom element order in the flattened import link tree. When processing the base element queue, user agents should only invoke callbacks up to the highest stable order, inclusively.

Note

Because imports load asynchronously, we need to divide a sorted element queue into the part where things have settled down (all imports have loaded), and the part where the loading is still happening, and thus the actual sorting order is not yet determined. For example, suppose you have the following document structure:

index.html:

<link rel="import" href="import.html">
...
<me-second></me-second>
...

import.html:

<me-first></me-first>

The order of custom elements in the flattened import link tree is me-first (1), me-second (2). However, it's very likely that the parser will find out about me-second sooner than me-first, since the latter requires loading the import.html. While the network stack is doing its job, the highest stable order stays at the beginning position. When import.html is ready, the order jumps all the way to me-second (2).

David Hyatt developed XBL 1.0, and Ian Hickson co-wrote XBL 2.0. These documents provided tremendous insight into the problem of behavior attachment and greatly influenced this specification.

Alex Russell and his considerable forethought triggered a new wave of enthusiasm around the subject of behavior attachment and how it can be applied practically on the Web.

Dominic Cooney and Roland Steiner worked tirelessly to scope the problem within the confines of the Web platform and provided a solid foundation for this document.

The editor would also like to thank Alex Komoroske, Angelina Fabbro, Anne van Kesteren, Boris Zbarsky, Brian Kardell, Daniel Buchner, Edward O'Connor, Eric Bidelman, Erik Arvidsson, Elliott Sprehn, Gabor Krizsanits, Hayato Ito, James Simonsen, Jonas Sicking, Ken Shirriff, Neel Goyal, Olli Pettay, Rafael Weinstein, Scott Miles, Steve Orvell, Tab Atkins, William Chan, and William Chen for their comments and contributions to this specification.

This list is too short. There's a lot of work left to do. Please contribute by reviewing and filing bugs—and don't forget to ask the editor to add your name into this section.

[CSP3]: Content Security Policy Level 3. Mike West; Antonio Sartori. W3C. 3 May 2023. W3C Working Draft. URL: https://www.w3.org/TR/CSP3/
[CSS-CASCADE-3]: CSS Cascading and Inheritance Level 3. Elika Etemad; Tab Atkins Jr.. W3C. 11 February 2021. W3C Recommendation. URL: https://www.w3.org/TR/css-cascade-3/
[CSS2]: Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. Bert Bos; Tantek Çelik; Ian Hickson; Håkon Wium Lie. W3C. 7 June 2011. W3C Recommendation. URL: https://www.w3.org/TR/CSS21/
[CUSTOM-ELEMENTS]: Custom Elements. Domenic Denicola. W3C. 3 May 2018. W3C Working Group Note. URL: https://www.w3.org/TR/custom-elements/
[Fetch]: Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]: HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[WHATWG-DOM]: DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[WHATWG-ENCODING]: Encoding Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://encoding.spec.whatwg.org/

HTML Imports

Abstract

Status of This Document

1. Conformance

2. Terminology

2.1 Import Dependent

3. Link Type "`import`"

4. Extensions to `HTMLLinkElement` Interface

5. Extensions to `Document` Interface

5.1 Additions to `document.open()` method

5.2 Additions to `document.write()` method

5.3 Additions to `document.close()` method

6. Loading Imports

6.1 Updating Branch

6.2 Requesting Import

6.3 Fetching Import

6.4 Imports and Content Security Policy

7. Parsing Imports

7.1 Additions to Prepare A Script Algorithm

7.2 Additions to Tree Construction Algorithm

7.3 Additions to Parsing XHTML Documents

8. Scripting in Imports

8.1 Additions to Script Enabling Criteria

8.2 Additions to document.currentScript

9. Style processing with Imports

9.1 Import Link Tree

9.2 Order of Appearances and Imports

10. Events in Imports

10.1 Additions to Event Handlers

11. Custom Element Processing

A. Acknowledgments

B. References

B.1 Normative references

HTML Imports

Abstract

Status of This Document

1. Conformance

2. Terminology

2.1 Import Dependent

3. Link Type "import"

4. Extensions to HTMLLinkElement Interface

5. Extensions to Document Interface

5.1 Additions to document.open() method

5.2 Additions to document.write() method

5.3 Additions to document.close() method

6. Loading Imports

6.1 Updating Branch

6.2 Requesting Import

6.3 Fetching Import

6.4 Imports and Content Security Policy

7. Parsing Imports

7.1 Additions to Prepare A Script Algorithm

7.2 Additions to Tree Construction Algorithm

7.3 Additions to Parsing XHTML Documents

8. Scripting in Imports

8.1 Additions to Script Enabling Criteria

8.2 Additions to document.currentScript

9. Style processing with Imports

9.1 Import Link Tree

9.2 Order of Appearances and Imports

10. Events in Imports

10.1 Additions to Event Handlers

11. Custom Element Processing

A. Acknowledgments

B. References

B.1 Normative references

3. Link Type "`import`"

4. Extensions to `HTMLLinkElement` Interface

5. Extensions to `Document` Interface

5.1 Additions to `document.open()` method

5.2 Additions to `document.write()` method

5.3 Additions to `document.close()` method