Living Standard — Last Updated 26 August 2024
html
elementSupport in all current engines.
Support in all current engines.
head
element followed by a body
element.html
element's start tag can be omitted
if the first thing inside the html
element is not a comment.html
element's end tag can be omitted if
the html
element is not immediately followed by a comment.[Exposed =Window ]
interface HTMLHtmlElement : HTMLElement {
[HTMLConstructor ] constructor ();
// also has obsolete members
};
The html
element represents the root of an HTML document.
Authors are encouraged to specify a lang
attribute on the root
html
element, giving the document's language. This aids speech synthesis tools to
determine what pronunciations to use, translation tools to determine what rules to use, and so
forth.
The html
element in the following example declares that the document's language
is English.
<!DOCTYPE html>
< html lang = "en" >
< head >
< title > Swapping Songs</ title >
</ head >
< body >
< h1 > Swapping Songs</ h1 >
< p > Tonight I swapped some of the songs I wrote with some friends, who
gave me some of the songs they wrote. I love sharing my music.</ p >
</ body >
</ html >
head
elementSupport in all current engines.
Support in all current engines.
html
element.iframe
srcdoc
document or if title information is available from a higher-level protocol: Zero or more elements of metadata content, of which no more than one is a title
element and no more than one is a base
element.title
element and no more than one is a base
element.head
element's start tag can be omitted if
the element is empty, or if the first thing inside the head
element is an
element.head
element's end tag can be omitted if
the head
element is not immediately followed by ASCII whitespace or a
comment.[Exposed =Window ]
interface HTMLHeadElement : HTMLElement {
[HTMLConstructor ] constructor ();
};
The head
element represents a collection of metadata for the
Document
.
The collection of metadata in a head
element can be large or small. Here is an
example of a very short one:
<!doctype html>
< html lang = en >
< head >
< title > A document with a short head</ title >
</ head >
< body >
...
Here is an example of a longer one:
<!DOCTYPE HTML>
< HTML LANG = "EN" >
< HEAD >
< META CHARSET = "UTF-8" >
< BASE HREF = "https://www.example.com/" >
< TITLE > An application with a long head</ TITLE >
< LINK REL = "STYLESHEET" HREF = "default.css" >
< LINK REL = "STYLESHEET ALTERNATE" HREF = "big.css" TITLE = "Big Text" >
< SCRIPT SRC = "support.js" ></ SCRIPT >
< META NAME = "APPLICATION-NAME" CONTENT = "Long headed application" >
</ HEAD >
< BODY >
...
The title
element is a required child in most situations, but when a
higher-level protocol provides title information, e.g., in the subject line of an email when HTML
is used as an email authoring format, the title
element can be omitted.
title
elementSupport in all current engines.
Support in all current engines.
head
element containing no other title
elements.[Exposed =Window ]
interface HTMLTitleElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString text ;
};
The title
element represents the document's title or name. Authors
should use titles that identify their documents even when they are used out of context, for
example in a user's history or bookmarks, or in search results. The document's title is often
different from its first heading, since the first heading does not have to stand alone when taken
out of context.
There must be no more than one title
element per document.
If it's reasonable for the Document
to have no title, then the
title
element is probably not required. See the head
element's content
model for a description of when the element is required.
title.text [ = value ]
Returns the child text content of the element.
Can be set, to replace the element's children with the given value.
The text
attribute's getter must return this title
element's child text
content.
The text
attribute's setter must string replace
all with the given value within this title
element.
Here are some examples of appropriate titles, contrasted with the top-level headings that might be used on those same pages.
< title > Introduction to The Mating Rituals of Bees</ title >
...
< h1 > Introduction</ h1 >
< p > This companion guide to the highly successful
< cite > Introduction to Medieval Bee-Keeping</ cite > book is...
The next page might be a part of the same site. Note how the title describes the subject matter unambiguously, while the first heading assumes the reader knows what the context is and therefore won't wonder if the dances are Salsa or Waltz:
< title > Dances used during bee mating rituals</ title >
...
< h1 > The Dances</ h1 >
The string to use as the document's title is given by the document.title
IDL attribute.
User agents should use the document's title when referring to the document in their user
interface. When the contents of a title
element are used in this way, the
directionality of that title
element should be used to set the directionality
of the document's title in the user interface.
base
elementSupport in all current engines.
Support in all current engines.
head
element containing no other base
elements.href
— Document base URL
target
— Default navigable for hyperlink navigation and form submission
[Exposed =Window ]
interface HTMLBaseElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString href ;
[CEReactions ] attribute DOMString target ;
};
The base
element allows authors to specify the document base URL for
the purposes of parsing URLs, and the name of the default
navigable for the purposes of following hyperlinks. The element does not
represent any content beyond this information.
There must be no more than one base
element per document.
A base
element must have either an href
attribute, a target
attribute, or both.
The href
content
attribute, if specified, must contain a valid URL potentially surrounded by
spaces.
A base
element, if it has an href
attribute,
must come before any other elements in the tree that have attributes defined as taking URLs, except the html
element (its manifest
attribute isn't affected by base
elements).
If there are multiple base
elements with href
attributes, all but the first are ignored.
The target
attribute,
if specified, must contain a valid navigable target name or keyword, which specifies
which navigable is to be used as the default when hyperlinks and forms in the
Document
cause navigation.
A base
element, if it has a target
attribute, must come before any elements in the tree that represent hyperlinks.
If there are multiple base
elements with target
attributes, all but the first are ignored.
To get an element's target, given an a
, area
, or
form
element element, and an optional string-or-null target
(default null), run these steps:
If target is null, then:
If element has a target
attribute, then set
target to that attribute's value.
Otherwise, if element's node document contains a
base
element with a target
attribute, set
target to the value of the target
attribute
of the first such base
element.
If target is not null, and contains an ASCII tab or newline and a
U+003C (<), then set target to "_blank
".
Return target.
A base
element that is the first base
element with an href
content attribute in a document tree has a
frozen base URL. The frozen base URL must be immediately
set for an element whenever any of the following
situations occur:
The base
element becomes the first base
element in tree
order with an href
content attribute in its
Document
.
The base
element is the first base
element in tree
order with an href
content attribute in its
Document
, and its href
content attribute is
changed.
To set the frozen base URL for an element element:
Let document be element's node document.
Let urlRecord be the result of parsing the
value of element's href
content attribute with
document's fallback base URL, and document's character encoding. (Thus, the base
element isn't affected by itself.)
If any of the following are true:
urlRecord is failure;
urlRecord's scheme is "data
" or "javascript
"; or
running Is base allowed for Document? on urlRecord and
document returns "Blocked
",
then set element's frozen base URL to document's fallback base URL and return.
Set element's frozen base URL to urlRecord.
The href
IDL
attribute, on getting, must return the result of running the following algorithm:
Let document be element's node document.
Let url be the value of the href
attribute of this element, if it has one, and the empty string otherwise.
Let urlRecord be the result of parsing
url with document's fallback base URL, and
document's character encoding.
(Thus, the base
element isn't affected by other base
elements or
itself.)
If urlRecord is failure, return url.
Return the serialization of urlRecord.
The href
IDL attribute, on setting, must set the href
content attribute to the given new value.
The target
IDL
attribute must reflect the content attribute of the same name.
In this example, a base
element is used to set the document base
URL:
<!DOCTYPE html>
< html lang = "en" >
< head >
< title > This is an example for the < base> element</ title >
< base href = "https://www.example.com/news/index.html" >
</ head >
< body >
< p > Visit the < a href = "archives.html" > archives</ a > .</ p >
</ body >
</ html >
The link in the above example would be a link to "https://www.example.com/news/archives.html
".
link
elementSupport in all current engines.
element; not to be confused with , which is represented by HTMLAnchorElement). This object inherits all of the properties and methods of the HTMLElement interface.">HTMLLinkElement
Support in all current engines.
noscript
element that is a child of a head
element.href
— Address of the hyperlink
crossorigin
— How the element handles crossorigin requests
rel
— Relationship between the document containing the hyperlink and the destination resource
media
— Applicable media
integrity
— Integrity metadata used in Subresource Integrity checks [SRI]
hreflang
— Language of the linked resource
type
— Hint for the type of the referenced resource
referrerpolicy
— Referrer policy for fetches initiated by the element
sizes
— Sizes of the icons (for rel
="icon
")
imagesrcset
— Images to use in different situations, e.g., high-resolution displays, small monitors, etc. (for rel
="preload
")
imagesizes
— Image sizes for different page layouts (for rel
="preload
")
as
— Potential destination for a preload request (for rel
="preload
" and rel
="modulepreload
")
blocking
— Whether the element is potentially render-blocking
color
— Color to use when customizing a site's icon (for rel
="mask-icon
")
disabled
— Whether the link is disabled
fetchpriority
— Sets the priority for fetches initiated by the element
title
attribute has special semantics on this element: Title of the link; CSS style sheet set name
[Exposed =Window ]
interface HTMLLinkElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute USVString href ;
[CEReactions ] attribute DOMString ? crossOrigin ;
[CEReactions ] attribute DOMString rel ;
[CEReactions ] attribute DOMString as ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList relList ;
[CEReactions ] attribute DOMString media ;
[CEReactions ] attribute DOMString integrity ;
[CEReactions ] attribute DOMString hreflang ;
[CEReactions ] attribute DOMString type ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList sizes ;
[CEReactions ] attribute USVString imageSrcset ;
[CEReactions ] attribute DOMString imageSizes ;
[CEReactions ] attribute DOMString referrerPolicy ;
[SameObject , PutForwards =value ] readonly attribute DOMTokenList blocking ;
[CEReactions ] attribute boolean disabled ;
[CEReactions ] attribute DOMString fetchPriority ;
// also has obsolete members
};
HTMLLinkElement includes LinkStyle ;
The link
element allows authors to link their document to other resources.
The address of the link(s) is given by the href
attribute. If the href
attribute is present, then its value must be a valid
non-empty URL potentially surrounded by spaces. One or both of the href
or imagesrcset
attributes must be present.
If both the href
and imagesrcset
attributes are absent, then the element does not
define a link.
The types of link indicated (the relationships) are given by the value of the rel
attribute, which, if present, must have a
value that is a unordered set of unique space-separated tokens. The allowed keywords and their meanings are defined in a later section. If the rel
attribute is absent, has no keywords, or if
none of the keywords used are allowed according to the definitions in this specification, then the
element does not create any links.
rel
's
supported tokens are the keywords defined in
HTML link types which are allowed on link
elements, impact
the processing model, and are supported by the user agent. The possible supported tokens are
alternate
,
dns-prefetch
,
expect
,
icon
,
manifest
,
modulepreload
,
next
,
pingback
,
preconnect
,
prefetch
,
preload
,
search
, and
stylesheet
.
rel
's supported
tokens must only include the tokens from this list that the user agent implements the
processing model for.
Theoretically a user agent could support the processing model for the canonical
keyword — if it were a search engine that executed
JavaScript. But in practice that's quite unlikely. So in most cases, canonical
ought not be included in rel
's supported
tokens.
A link
element must have either a rel
attribute or an itemprop
attribute, but not both.
If a link
element has an itemprop
attribute,
or has a rel
attribute that contains only keywords that are
body-ok, then the element is said to be allowed in the body. This means
that the element can be used where phrasing content is expected.
If the rel
attribute is used, the element can
only sometimes be used in the body
of the page. When used with the itemprop
attribute, the element can be used both in the
head
element and in the body
of the page, subject to the constraints of
the microdata model.
Two categories of links can be created using the link
element: links to external resources and hyperlinks. The link types section defines
whether a particular link type is an external resource or a hyperlink. One link
element can create multiple links (of which some might be external resource links and some might be hyperlinks); exactly which and how many links are created depends on the
keywords given in the rel
attribute. User agents must process
the links on a per-link basis, not a per-element basis.
Each link created for a link
element is handled separately. For
instance, if there are two link
elements with rel="stylesheet"
,
they each count as a separate external resource, and each is affected by its own attributes
independently. Similarly, if a single link
element has a rel
attribute with the value next stylesheet
,
it creates both a hyperlink (for the next
keyword) and
an external resource link (for the stylesheet
keyword), and they are affected by other attributes (such as media
or title
)
differently.
For example, the following link
element creates two hyperlinks (to the same page):
< link rel = "author license" href = "/about" >
The two links created by this element are one whose semantic is that the target page has information about the current page's author, and one whose semantic is that the target page has information regarding the license under which the current page is provided.
Hyperlinks created with the link
element and its
rel
attribute apply to the whole document. This contrasts with
the rel
attribute of a
and area
elements, which indicates the type of a link whose context is given by the link's location within
the document.
Unlike those created by a
and area
elements, hyperlinks created by link
elements are not displayed as
part of the document by default, in user agents that support the suggested
default rendering. And even if they are force-displayed using CSS, they have no
activation behavior. Instead, they primarily provide semantic information which might
be used by the page or by other software that consumes the page's contents. Additionally, the user
agent can provide
its own UI for following such hyperlinks.
The exact behavior for links to external resources depends on the exact relationship, as defined for the relevant link type.
The crossorigin
attribute is a CORS settings attribute. It is intended for use with external resource links.
The media
attribute
says which media the resource applies to. The value must be a valid media query
list.
Support in all current engines.
The integrity
attribute represents the integrity
metadata for requests which this element is responsible for. The value is text. The
attribute must only be specified on link
elements that have a rel
attribute that contains the stylesheet
, preload
, or modulepreload
keyword. [SRI]
The hreflang
attribute on the link
element has the same semantics as the hreflang
attribute on the a
element.
The type
attribute
gives the MIME type of the linked resource. It is purely advisory. The value must be
a valid MIME type string.
For external resource links, the type
attribute is used as a hint to user agents so that they can
avoid fetching resources they do not support.
The referrerpolicy
attribute is a referrer policy
attribute. It is intended for use with external
resource links, where it helps set the referrer policy used when fetching and processing the linked resource.
[REFERRERPOLICY]
The title
attribute
gives the title of the link. With one exception, it is purely advisory. The value is text. The
exception is for style sheet links that are in a document tree, for which the title
attribute defines CSS
style sheet sets.
The title
attribute on link
elements differs from the global title
attribute of most other
elements in that a link without a title does not inherit the title of the parent element: it
merely has no title.
The imagesrcset
attribute may be present, and is a srcset attribute.
The imagesrcset
and href
attributes (if width
descriptors are not used) together contribute the image
sources to the source set.
If the imagesrcset
attribute is present and has any
image candidate strings using a width
descriptor, the imagesizes
attribute must also be present, and is a
sizes attribute. The imagesizes
attribute
contributes the source size to the source set.
The imagesrcset
and imagesizes
attributes must only be specified on
link
elements that have both a rel
attribute that
specifies the preload
keyword, as well as an as
attribute in the "image
" state.
These attributes allow preloading the appropriate resource that is later used by an
img
element that has the corresponding values for its srcset
and sizes
attributes:
< link rel = "preload" as = "image"
imagesrcset = "wolf_400px.jpg 400w, wolf_800px.jpg 800w, wolf_1600px.jpg 1600w"
imagesizes = "50vw" >
<!-- ... later, or perhaps inserted dynamically ... -->
< img src = "wolf.jpg" alt = "A rad wolf"
srcset = "wolf_400px.jpg 400w, wolf_800px.jpg 800w, wolf_1600px.jpg 1600w"
sizes = "50vw" >
Note how we omit the href
attribute, as it would only
be relevant for browsers that do not support imagesrcset
, and in those cases it would likely cause the
incorrect image to be preloaded.
The imagesrcset
attribute can be combined with the
media
attribute to preload the appropriate resource
selected from a picture
element's sources, for art direction:
< link rel = "preload" as = "image"
imagesrcset = "dog-cropped-1x.jpg, dog-cropped-2x.jpg 2x"
media = "(max-width: 800px)" >
< link rel = "preload" as = "image"
imagesrcset = "dog-wide-1x.jpg, dog-wide-2x.jpg 2x"
media = "(min-width: 801px)" >
<!-- ... later, or perhaps inserted dynamically ... -->
< picture >
< source srcset = "dog-cropped-1x.jpg, dog-cropped-2x.jpg 2x"
media = "(max-width: 800px)" >
< img src = "dog-wide-1x.jpg" srcset = "dog-wide-2x.jpg 2x"
alt = "An awesome dog" >
</ picture >
The sizes
attribute
gives the sizes of icons for visual media. Its value, if present, is merely advisory. User agents may use the value to decide which icon(s) to use if multiple icons are
available. If specified, the attribute must have a value that is an unordered set of
unique space-separated tokens which are ASCII case-insensitive. Each value
must be either an ASCII case-insensitive match for the string "any
", or a value that consists of two valid non-negative integers that do not have a leading U+0030 DIGIT
ZERO (0) character and that are separated by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN
CAPITAL LETTER X character. The attribute must only be specified on link
elements
that have a rel
attribute that specifies the icon
keyword or the apple-touch-icon
keyword.
The apple-touch-icon
keyword is a registered extension to the predefined set of link types, but user
agents are not required to support it in any way.
The as
attribute
specifies the potential destination for a
preload request for the resource given by the href
attribute.
It is an enumerated attribute. Each potential destination is a keyword for this
attribute, mapping to a state of the same name. The attribute must be specified on
link
elements that have a rel
attribute that
contains the preload
keyword. It may be specified on
link
elements that have a rel
attribute that
contains the modulepreload
keyword; in such cases it must
have a value which is a script-like
destination. For other link
elements, it must not be specified.
The processing model for how the as
attribute is
used is given in an individual link type's fetch and process the linked resource
algorithm.
The attribute does not have a missing value
default or invalid value default, meaning that invalid
or missing values for the attribute map to no state. This is accounted for in the processing
model. For preload
links, both conditions are an error; for
modulepreload
links, a missing value will be treated as
"script
".
The blocking
attribute is a blocking attribute. It is used by link types stylesheet
and expect
, and it must only be specified on link elements
that have a rel
attribute containing those keywords.
The color
attribute is
used with the mask-icon
link type. The attribute must only be specified on
link
elements that have a rel
attribute that
contains the mask-icon
keyword. The value must be a string that matches the
CSS <color> production, defining a suggested color that user agents can use to
customize the display of the icon that the user sees when they pin your site.
This specification does not have any user agent requirements for the color
attribute.
The mask-icon
keyword is a registered extension to the predefined set of link types, but user
agents are not required to support it in any way.
link
elements have an associated explicitly enabled boolean. It is
initially false.
The disabled
attribute is a boolean attribute that is used with the stylesheet
link type. The attribute must only be specified on
link
elements that have a rel
attribute that
contains the stylesheet
keyword.
Whenever the disabled
attribute is removed, set the
link
element's explicitly enabled attribute to true.
Removing the disabled
attribute dynamically, e.g.,
using document.querySelector("link").removeAttribute("disabled")
, will
fetch and apply the style sheet:
< link disabled rel = "alternate stylesheet" href = "css/pooh" >
The fetchpriority
attribute is a fetch
priority attribute that is intended for use with external resource links, where it is used to set the priority used when fetching and processing the linked
resource.
element and the current document.">HTMLLinkElement/rel
Support in all current engines.
The IDL attributes
href
,
hreflang
,
integrity
,
media
,
rel
,
sizes
,
type
,
blocking
, and
disabled
each must reflect the respective content attributes of the same name.
There is no reflecting IDL attribute for the color
attribute, but this might be added later.
Support in all current engines.
The as
IDL
attribute must reflect the as
content attribute,
limited to only known values.
The crossOrigin
IDL attribute must reflect the
crossorigin
content attribute, limited to only
known values.
element defining which referrer is sent when fetching the resource.">HTMLLinkElement/referrerPolicy
Support in all current engines.
The referrerPolicy
IDL attribute must
reflect the referrerpolicy
content
attribute, limited to only known values.
The fetchPriority
IDL attribute must
reflect the fetchpriority
content
attribute, limited to only known values.
The imageSrcset
IDL attribute must reflect the
imagesrcset
content attribute.
The imageSizes
IDL attribute must reflect the
imagesizes
content attribute.
element and the current document.">HTMLLinkElement/relList
Support in all current engines.
The relList
IDL attribute must reflect the rel
content attribute.
The relList
attribute can be used for
feature detection, by calling its supports()
method to check which types of links are supported.
media
attributeIf the link is a hyperlink then the media
attribute is purely advisory, and describes for which media the document in question was
designed.
However, if the link is an external resource link, then the media
attribute is prescriptive. The user agent must apply the
external resource when the media
attribute's value
matches the environment and the other relevant conditions apply, and must not apply
it otherwise.
The default, if the media
attribute is
omitted, is "all
", meaning that by default links apply to all media.
The external resource might have further restrictions defined within that limit
its applicability. For example, a CSS style sheet might have some @media
blocks. This specification does not override such further restrictions or requirements.
type
attributeIf the type
attribute is present, then the user agent must
assume that the resource is of the given type (even if that is not a valid MIME type
string, e.g. the empty string). If the attribute is omitted, but the external
resource link type has a default type defined, then the user agent must assume that the
resource is of that type. If the UA does not support the given MIME type for the
given link relationship, then the UA should not fetch and process the linked
resource; if the UA does support the given MIME type for the given link
relationship, then the UA should fetch and process the linked resource at the
appropriate time as specified for the external resource link's particular type.
If the attribute is omitted, and the external resource link type does not have a
default type defined, but the user agent would fetch and process the linked resource
if the type was known and supported, then the user agent should fetch and process the linked
resource under the assumption that it will be supported.
User agents must not consider the type
attribute
authoritative — upon fetching the resource, user agents must not use the type
attribute to determine its actual type. Only the actual type
(as defined in the next paragraph) is used to determine whether to apply the resource,
not the aforementioned assumed type.
If the external resource link type defines rules for processing the resource's Content-Type metadata, then those rules apply. Otherwise, if the resource is expected to be an image, user agents may apply the image sniffing rules, with the official type being the type determined from the resource's Content-Type metadata, and use the resulting computed type of the resource as if it was the actual type. Otherwise, if neither of these conditions apply or if the user agent opts not to apply the image sniffing rules, then the user agent must use the resource's Content-Type metadata to determine the type of the resource. If there is no type metadata, but the external resource link type has a default type defined, then the user agent must assume that the resource is of that type.
The stylesheet
link type defines rules for
processing the resource's Content-Type metadata.
Once the user agent has established the type of the resource, the user agent must apply the resource if it is of a supported type and the other relevant conditions apply, and must ignore the resource otherwise.
If a document contains style sheet links labeled as follows:
< link rel = "stylesheet" href = "A" type = "text/plain" >
< link rel = "stylesheet" href = "B" type = "text/css" >
< link rel = "stylesheet" href = "C" >
...then a compliant UA that supported only CSS style sheets would fetch the B and C files, and
skip the A file (since text/plain
is not the MIME type for CSS style
sheets).
For files B and C, it would then check the actual types returned by the server. For those that
are sent as text/css
, it would apply the styles, but for those labeled as
text/plain
, or any other type, it would not.
If one of the two files was returned without a Content-Type metadata, or with a
syntactically incorrect type like Content-Type: "null"
, then the
default type for stylesheet
links would kick in. Since that
default type is text/css
, the style sheet would nonetheless be applied.
link
elementAll external resource
links have a fetch and process the linked resource algorithm, which takes a
link
element el. They also have linked resource fetch setup
steps which take a link
element el and request request. Individual link types may provide
their own fetch and process the linked resource algorithm, but unless explicitly
stated, they use the default fetch and process the linked resource algorithm.
Similarly, individual link types may provide their own linked resource fetch setup
steps, but unless explicitly stated, these steps just return true.
The default fetch and process the linked resource, given a link
element
el, is as follows:
Let options be the result of creating link options from el.
Let request be the result of creating a link request given options.
If request is null, then return.
Set request's synchronous flag.
Run the linked resource fetch setup steps, given el and request. If the result is false, then return.
Set request's initiator
type to "css
" if el's rel
attribute contains the keyword stylesheet
; "link
" otherwise.
Fetch request with processResponseConsumeBody set to the following steps given response response and null, failure, or a byte sequence bodyBytes:
Let success be true.
If any of the following are true:
then set success to false.
Note that content-specific errors, e.g., CSS parse errors or PNG decoding errors, do not affect success.
Otherwise, wait for the link resource's critical subresources to finish loading.
The specification that defines a link type's critical subresources (e.g., CSS) is expected to describe how these subresources are fetched and processed. However, since this is not currently explicit, this specification describes waiting for a link resource's critical subresources to be fetched and processed, with the expectation that this will be done correctly.
Process the linked resource given el, success, response, and bodyBytes.
To create a link request given a link processing options options:
If options's destination is null, then return null.
Let url be the result of encoding-parsing a URL given options's href, relative to options's base URL.
Passing the base URL instead of a document or environment is tracked by issue #9715.
If url is failure, then return null.
Let request be the result of creating a potential-CORS request given url, options's destination, and options's crossorigin.
Set request's policy container to options's policy container.
Set request's integrity metadata to options's integrity.
Set request's cryptographic nonce metadata to options's cryptographic nonce metadata.
Set request's referrer policy to options's referrer policy.
Set request's client to options's environment.
Set request's priority to options's fetch priority.
Return request.
User agents may opt to only try to fetch and process such resources when they are needed, instead of pro-actively fetching all the external resources that are not applied.
Similar to the fetch and process the linked resource algorithm, all external resource links have a process the linked
resource algorithm which takes a link
element el, boolean
success, a response response, and a
byte sequence bodyBytes. Individual link types may provide their own
process the linked resource algorithm, but unless explicitly stated, that algorithm
does nothing.
Unless otherwise specified for a given rel
keyword, the
element must delay the load event of the element's node document until
all the attempts to fetch and process the linked resource and its critical
subresources are complete. (Resources that the user agent has not yet attempted to fetch
and process, e.g., because it is waiting for the resource to be needed, do not delay the
load event.)
Link
` headersAll link types that can be external resource
links define a process a link header algorithm, which takes a link
processing options. This algorithm defines whether and how they react to appearing in an
HTTP `Link
` response header.
For most link types, this algorithm does nothing. The summary table is a good reference to quickly know whether a link type has defined process a link header steps.
A link processing options is a struct. It has the following items:
link
")Document
Document
auto
)A link processing options has a base URL and an href rather than a parsed URL because the URL could be a result of the options's source set.
To create link options from element given a link
element
el:
Let document be el's node document.
Let options be a new link processing options with
as
attribute.crossorigin
content attributereferrerpolicy
content attributefetchpriority
content attributeIf el has an href
attribute, then set
options's href to the value of
el's href
attribute.
If el has an integrity
attribute,
then set options's integrity to the
value of el's integrity
content
attribute.
If el has a type
attribute, then set
options's type to the value of
el's type
attribute.
Assert: options's href is not the empty string, or options's source set is not null.
A link
element with neither an href
or an
imagesrcset
does not represent a link.
Return options.
To extract links from headers given a header list headers:
Let links be a new list.
Let rawLinkHeaders be the result of getting, decoding, and splitting
`Link
` from response's header list.
For each linkHeader of rawLinkHeaders:
Return links.
To process link headers given a Document
doc,
a response response, and a
"pre-media
" or "media
" phase:
Let links be the result of extracting links from response's header list.
For each linkObject in links:
Let rel be linkObject["relation_type
"].
Let attribs be linkObject["target_attributes
"].
Let expectedPhase be "media
" if either "srcset
", "imagesrcset
", or "media
" exist in
attribs; otherwise "pre-media
".
If expectedPhase is not phase, then continue.
If attribs["media
"] exists and attribs["media
"]
does not match the environment, then
continue.
Let options be a new link processing options with
target_uri
"]Apply link options from parsed header attributes to options given attribs.
If attribs["imagesrcset
"] exists and attribs["imagesizes
"] exists,
then set options's source set to the
result of creating a source set given
linkObject["target_uri
"], attribs["imagesrcset
"], attribs["imagesizes
"], and null.
Run the process a link header steps for rel given options.
To apply link options from parsed header attributes to a link processing options options given attribs:
If attribs["as
"] exists, then set options's destination to the result of translating attribs["as
"].
If attribs["crossorigin
"] exists and is an ASCII case-insensitive match for one of
the CORS settings attribute keywords,
then set options's crossorigin to the
CORS settings attribute state corresponding to that keyword.
If attribs["integrity
"] exists, then set options's integrity to attribs["integrity
"].
If attribs["referrerpolicy
"]
exists and is an ASCII case-insensitive match for
some referrer policy, then set options's referrer policy to that referrer policy.
If attribs["nonce
"]
exists, then set options's nonce to attribs["nonce
"].
If attribs["type
"] exists, then set options's type to attribs["type
"].
If attribs["fetchpriority
"]
exists and is an ASCII case-insensitive match for
a fetch priority attribute keyword, then set options's fetch priority to that fetch priority
attribute keyword.
Early hints allow user-agents to perform some operations, such as to speculatively load resources that are likely to be used by the document, before the navigation request is fully handled by the server and a response code is served. Servers can indicate early hints by serving a response with a 103 status code before serving the final response.[RFC8297]
For compatibility reasons early hints are typically delivered over HTTP/2 or above, but for readability we use HTTP/1.1-style notation below.
For example, given the following sequence of responses:
103 Early Hint Link: </image.png>; rel=preload; as=image
200 OK Content-Type: text/html <!DOCTYPE html> ... <img src="/image.png">
the image will start loading before the HTML content arrives.
Only the first early hint response served during the navigation is handled, and it is discarded if it is succeeded by a cross-origin redirect.
In addition to the `Link
` headers, it is possible that the 103
response contains a Content Security Policy header, which is enforced when processing
the early hint.
For example, given the following sequence of responses:
103 Early Hint Content-Security-Policy: style-src: self; Link: </style.css>; rel=preload; as=style
103 Early Hint Link: </image.png>; rel=preload; as=image
302 Redirect Location: /alternate.html
200 OK Content-Security-Policy: style-src: none; Link: </font.ttf>; rel=preload; as=font
The font and style would be loaded, and the image will be discarded, as only the first early hint response in the final redirect chain is respected. The late Content Security Policy header comes after the request to fetch the style has already been performed, but the style will not be accessible to the document.
To process early hint headers given a response response and an environment reservedEnvironment:
Early-hint `Link
` headers are always processed
before `Link
` headers from the final response, followed by link
elements. This is
equivalent to prepending the contents of the early and final `Link
` headers to the Document
's head
element,
in respective order.
Let earlyPolicyContainer be the result of creating a policy container from a fetch response given response and reservedEnvironment.
This allows the early hint response to include a Content Security Policy which would be enforced when fetching the early hint request.
Let links be the result of extracting links from response's header list.
Let earlyHints be an empty list.
For each linkObject in links:
The moment we receive the early hint link header, we begin fetching earlyRequest. If it comes back before the
Document
is created, we set earlyResponse to the response of that fetch and
once the Document
is created we commit it (by making it available in the map
of preloaded resources as if it was a link
element). If the
Document
is created first, the response is
committed as soon as it becomes available.
Let rel be linkObject["relation_type
"].
Let options be a new link processing options with
target_uri
"]early-hint
"Let attribs be linkObject["target_attributes
"].
Only the as
, crossorigin
, integrity
, and type
attributes are handled as part of early hint processing. The other ones, in particular blocking
, imagesrcset
, imagesizes
, and media
are only applicable once a Document
is
created.
Apply link options from parsed header attributes to options given attribs.
Run the process a link header steps for rel given options.
Append options to earlyHints.
Return the following substeps given Document
doc: for each options in earlyHints:
If options's on document ready is null, then set options's document to doc.
Otherwise, call options's on document ready with doc.
link
elementInteractive user agents may provide users with a means to follow the hyperlinks created using the link
element, somewhere
within their user interface. Such invocations of the follow
the hyperlink algorithm must set the userInvolvement argument to "browser UI
". The exact interface is not defined by this
specification, but it could include the following information (obtained from the element's
attributes, again as defined below), in some form or another (possibly simplified), for each
hyperlink created with each link
element in the document:
rel
attribute)title
attribute).href
attribute).hreflang
attribute).media
attribute).User agents could also include other information, such as the type of the resource (as given by
the type
attribute).
meta
element