search
element with form functionality — Last Updated 1 December 2021a
and area
elementsa
and area
elementsalternate
"author
"bookmark
"canonical
"dns-prefetch
"external
"help
"icon
"license
"manifest
"modulepreload
"nofollow
"noopener
"noreferrer
"opener
"pingback
"preconnect
"prefetch
"preload
"prerender
"search
"stylesheet
"tag
"Links are a conceptual construct, created by a
, area
,
form
, search
,
and link
elements, that represent
a connection between two resources, one of which is the current Document
. There are
two kinds of links in HTML:
These are links to resources that are to be used to augment the current document, generally automatically processed by the user agent. All external resource links have a fetch and process the linked resource algorithm which describes how the resource is obtained.
These are links to other resources that are generally exposed to the user by the user agent so that the user can cause the user agent to navigate to those resources, e.g. to visit them in a browser or download them.
For link
elements with an href
attribute and a
rel
attribute, links must be created for the keywords of the
rel
attribute, as defined for those keywords in the link types section.
Similarly, for a
and area
elements with an href
attribute and a rel
attribute, links must be created for the keywords of the
rel
attribute as defined for those keywords in the link types section. Unlike link
elements, however,
a
and area
elements with an href
attribute that either do not have a rel
attribute, or
whose rel
attribute has no keywords that are defined as
specifying hyperlinks, must also create a hyperlink.
This implied hyperlink has no special meaning (it has no link type)
beyond linking the element's node document to the resource given by the element's href
attribute.
Similarly, for forms
with a rel
attribute, links must be created for the keywords of the rel
attribute as defined for those keywords in the link types section.
forms
that do not have a rel
attribute,
or whose rel
attribute has no keywords that are defined as
specifying hyperlinks, must also create a hyperlink.
A hyperlink can have one or more hyperlink annotations that modify the processing semantics of that hyperlink.
a
and area
elementsThe href
attribute on a
and area
elements must have a value that is a valid
URL potentially surrounded by spaces.
The href
attribute on a
and
area
elements is not required; when those elements do not have href
attributes they do not create hyperlinks.
The target
attribute, if present, must be a valid browsing context name or keyword. It gives the
name of the browsing context that will be used. User agents use this
name when following hyperlinks.
When an a
or area
element's activation behavior is
invoked, the user agent may allow the user to indicate a preference regarding whether the
hyperlink is to be used for navigation or whether the resource it
specifies is to be downloaded.
In the absence of a user preference, the default should be navigation if the element has no
download
attribute, and should be to download the
specified resource if it does.
Whether determined by the user's preferences or via the presence or absence of the attribute, if the decision is to use the hyperlink for navigation then the user agent must follow the hyperlink, and if the decision is to use the hyperlink to download a resource, the user agent must download the hyperlink. These terms are defined in subsequent sections below.
The download
attribute, if present, indicates that the author intends the hyperlink to be used for downloading a resource. The attribute may have a value; the
value, if any, specifies the default filename that the author recommends for use in labeling the
resource in a local file system. There are no restrictions on allowed values, but authors are
cautioned that most file systems have limitations with regard to what punctuation is supported in
filenames, and user agents are likely to adjust filenames accordingly.
Support in all current engines.
The ping
attribute, if present, gives the URLs of the
resources that are interested in being notified if the user follows the hyperlink. The value must
be a set of space-separated tokens, each of which must be a valid non-empty
URL whose scheme is an HTTP(S)
scheme. The value is used by the user agent for hyperlink
auditing.
The rel
attribute on a
and area
elements controls what kinds of links the elements create. The attribute's value must be an
unordered set of unique space-separated tokens. The allowed
keywords and their meanings are defined below.
rel
's supported tokens are the keywords defined in HTML link types which are allowed on a
and area
elements, impact the processing model, and are supported by the user agent. The possible supported tokens are noreferrer
, noopener
, and opener
. rel
's supported tokens must only include the tokens from this
list that the user agent implements the processing model for.
The rel
attribute has no default value. If the
attribute is omitted or if none of the values in the attribute are recognized by the user agent,
then the document has no particular relationship with the destination resource other than there
being a hyperlink between the two.
The hreflang
attribute on a
elements that create hyperlinks, if
present, gives the language of the linked resource. It is purely advisory. The value must be a
valid BCP 47 language tag. [BCP47] User agents must not consider this
attribute authoritative — upon fetching the resource, user agents must use only language
information associated with the resource to determine its language, not metadata included in the
link to the resource.
The type
attribute, if present, gives the MIME type of the linked resource. It is purely
advisory. The value must be a valid MIME type string. User agents must
not consider the type
attribute authoritative —
upon fetching the resource, user agents must not use metadata included in the link to the resource
to determine its type.
The referrerpolicy
attribute is a referrer
policy attribute. Its purpose is to set the referrer policy used when
following hyperlinks. [REFERRERPOLICY]
a
and area
elementsinterface mixin HTMLHyperlinkElementUtils {
[CEReactions ] stringifier attribute USVString href ;
readonly attribute USVString origin ;
[CEReactions ] attribute USVString protocol ;
[CEReactions ] attribute USVString username ;
[CEReactions ] attribute USVString password ;
[CEReactions ] attribute USVString host ;
[CEReactions ] attribute USVString hostname ;
[CEReactions ] attribute USVString port ;
[CEReactions ] attribute USVString pathname ;
[CEReactions ] attribute USVString search ;
[CEReactions ] attribute USVString hash ;
};
hyperlink.toString()
hyperlink.href
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL.
Can be set, to change the URL.
hyperlink.origin
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL's origin.
hyperlink.protocol
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL's scheme.
Can be set, to change the URL's scheme.
hyperlink.username
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL's username.
Can be set, to change the URL's username.
hyperlink.password
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL's password.
Can be set, to change the URL's password.
hyperlink.host
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL's host and port (if different from the default port for the scheme).
Can be set, to change the URL's host and port.
hyperlink.hostname
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL's host.
Can be set, to change the URL's host.
hyperlink.port
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL's port.
Can be set, to change the URL's port.
hyperlink.pathname
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL's path.
Can be set, to change the URL's path.
hyperlink.search
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL's query (includes leading "?
" if
non-empty).
Can be set, to change the URL's query (ignores leading "?
").
hyperlink.hash
Support in all current engines.
Support in all current engines.
Returns the hyperlink's URL's fragment (includes leading "#
" if
non-empty).
Can be set, to change the URL's fragment (ignores leading "#
").
An element implementing the HTMLHyperlinkElementUtils
mixin has an associated url (null or a URL). It is initially null.
An element implementing the HTMLHyperlinkElementUtils
mixin has an associated set the url algorithm, which runs these steps:
If this element's href
content attribute is
absent, set this element's url to null.
Otherwise, parse this element's href
content
attribute value relative to this element's node document. If parsing is successful, set this element's url to the result; otherwise, set this element's
url to null.
When elements implementing the HTMLHyperlinkElementUtils
mixin are created, and
whenever those elements have their href
content
attribute set, changed, or removed, the user agent must set the url.
This is only observable for blob:
URLs as
parsing them involves a Blob URL Store lookup.
An element implementing the HTMLHyperlinkElementUtils
mixin has an associated
reinitialize url algorithm, which runs these
steps:
If element's url is non-null, its scheme is "blob
", and it has an
opaque path, then terminate these steps.
To update href
, set the element's href
content attribute's value to the element's url, serialized.
The href
getter steps are:
If url is null and this has no href
content attribute, return the empty string.
Otherwise, if url is null, return this's href
content attribute's value.
Return url, serialized.
The href
setter steps are to set this's
href
content attribute's value to the given value.
The origin
getter steps are:
Return the serialization of this's url's origin.
The protocol
getter steps are:
The protocol
setter steps are:
Basic URL parse the given value, followed by ":
", with this's url as
url and scheme start state as
state override.
Because the URL parser ignores multiple consecutive colons, providing a value
of "https:
" (or even "https::::
") is the same as
providing a value of "https
".
The username
getter steps are:
The username
setter steps are:
If url is null or url cannot have a username/password/port, then return.
Set the username, given url and the given value.
The password
getter steps are:
If url is null, then return the empty string.
Return url's password.
The password
setter steps are:
If url is null or url cannot have a username/password/port, then return.
Set the password, given url and the given value.
The host
getter steps are:
If url or url's host is null, return the empty string.
If url's port is null, return url's host, serialized.
Return url's host, serialized, followed by ":
" and url's port, serialized.
The host
setter steps are:
If url is null or url has an opaque path, then return.
Basic URL parse the given value, with url as url and host state as state override.
The hostname
getter steps are:
If url or url's host is null, return the empty string.
Return url's host, serialized.
The hostname
setter steps are:
If url is null or url has an opaque path, then return.
Basic URL parse the given value, with url as url and hostname state as state override.
The port
getter steps are:
If url or url's port is null, return the empty string.
Return url's port, serialized.
The port
setter steps are:
If url is null or url cannot have a username/password/port, then return.
If the given value is the empty string, then set url's port to null.
Otherwise, basic URL parse the given value, with url as url and port state as state override.
The pathname
getter steps are:
If url is null, then return the empty string.
Return the result of URL path serializing url.
The pathname
setter steps are:
If url is null or url has an opaque path, then return.
Set url's path to the empty list.
Basic URL parse the given value, with url as url and path start state as state override.
The search
getter steps are:
If url is null, or url's query is either null or the empty string, return the empty string.
Return "?
", followed by url's query.
The search
setter steps are:
If url is null, terminate these steps.
If the given value is the empty string, set url's query to null.
Otherwise:
Let input be the given value with a single leading "?
"
removed, if any.
Set url's query to the empty string.
Basic URL parse input, with null, this element's node document's document's character encoding, url as url, and query state as state override.
The hash
getter steps are:
If url is null, or url's fragment is either null or the empty string, return the empty string.
Return "#
", followed by url's fragment.
The hash
setter steps are:
If url is null, then return.
If the given value is the empty string, set url's fragment to null.
Otherwise:
Let input be the given value with a single leading "#
"
removed, if any.
Set url's fragment to the empty string.
Basic URL parse input, with url as url and fragment state as state override.
An element element cannot navigate if one of the following is true:
a
element and is not connected.This is also used by form submission for
forms. The exception for a
elements is for
compatibility with web content.
To get an element's noopener, given an a
, area
,
form
, or search
element element and a string target:
If element's link types include the noopener
or noreferrer
keyword, then return true.
If element's link types
do not include the opener
keyword and target is an
ASCII case-insensitive match for "_blank
", then return
true.
Return false.
To follow the hyperlink created by an element subject, given an optional hyperlinkSuffix (default null):
If subject cannot navigate, then return.
Let replace be false.
Let source be subject's node document's browsing context.
Let targetAttributeValue be the empty string.
If subject is an a
or area
element, then set
targetAttributeValue to the result of getting
an element's target given subject.
Let noopener be the result of getting an element's noopener with subject and targetAttributeValue.
Let target and windowType be the result of applying the rules for choosing a browsing context given targetAttributeValue, source, and noopener.
If target is null, then return.
Parse a URL given subject's href
attribute, relative to subject's node
document.
If that is successful, let URL be the resulting URL string.
Otherwise, if parsing the URL failed, the user agent may report the error to the user in a user-agent-specific manner, may queue an element task on the DOM manipulation task source given subject to navigate the target browsing context to an error page to report the error, or may ignore the error and do nothing. In any case, the user agent must then return.
If hyperlinkSuffix is non-null, then append it to URL.
Let request be a new request whose URL is URL and whose referrer policy is the current state of
subject's referrerpolicy
content attribute.
If subject's link
types includes the noreferrer
keyword, then set
request's referrer to "no-referrer
".
Let historyHandling be "replace
" if
windowType is not "existing or none
"; otherwise, "default
".
Unlike many other types of navigations, following hyperlinks does not have
special "replace
" behavior for when documents are not
completely loaded. This is true for both user-initiated instances of following
hyperlinks, as well as script-triggered ones via, e.g., aElement.click()
.
Queue an element task on the DOM manipulation task source given subject to navigate target to request with historyHandling set to historyHandling and the source browsing context set to source.
Support in all current engines.
In some cases, resources are intended for later use rather than immediate viewing. To indicate
that a resource is intended to be downloaded for use later, rather than immediately used, the
download
attribute can be specified on the
a
or area
element that creates the hyperlink to that
resource.
The attribute can furthermore be given a value, to specify the filename that user agents are
to use when storing the resource in a file system. This value can be overridden by the `Content-Disposition
` HTTP header's filename parameters.
[RFC6266]
In cross-origin situations, the download
attribute has to be combined with the `Content-Disposition
` HTTP header, specifically with the
attachment
disposition type, to avoid the user being warned of possibly
nefarious activity. (This is to protect users from being made to download sensitive personal or
confidential information without their full understanding.)
The following allowed to download algorithm takes an initiator browsing context and an instantiator browsing context, and returns a boolean indicating whether or not downloading is allowed:
If the initiator browsing context's sandboxing flags has the sandboxed downloads browsing context flag set, then return false.
If the instantiator browsing context is non-null, and its sandboxing flags has the sandboxed downloads browsing context flag set, then return false.
Optionally, the user agent may return false, if it believes doing so would safeguard the user from a potentially hostile download.
Return true.
To download the hyperlink created by an element subject, given an optional hyperlinkSuffix (default null):
If subject cannot navigate, then return.
Run the allowed to download algorithm with the subject's node document's browsing context and null. If the algorithm returns false, then return.
Parse a URL given subject's href
attribute, relative to subject's node
document.
If parsing the URL fails, the user agent may report the error to the user in a user-agent-specific manner, may navigate to an error page to report the error, or may ignore the error and do nothing. In either case, the user agent must return.
Otherwise, let URL be the resulting URL string.
If hyperlinkSuffix is non-null, then append it to URL.
Run these steps in parallel:
Let request be a new request whose
URL is URL,
client is entry settings object,
initiator is "download
",
destination is the empty string, and whose
synchronous flag and use-URL-credentials flag are set.
Handle the result of fetching request as a download.
When a user agent is to handle a resource obtained from a fetch as a download, it should provide the user with a way to save the resource for later use, if a resource is successfully obtained. Otherwise, it should report any problems downloading the file to the user.
If the user agent needs a filename for a resource being handled as a download, it should select one using the following algorithm.
This algorithm is intended to mitigate security dangers involved in downloading files from untrusted sites, and user agents are strongly urged to follow it.
Let filename be the undefined value.
If the resource has a `Content-Disposition
`
header, that header specifies the attachment
disposition type, and the
header includes filename information, then let filename have the value specified by
the header, and jump to the step labeled sanitize below. [RFC6266]
Let interface origin be the origin of the Document
in which the download or navigate action resulting in the
download was initiated, if any.
Let resource origin be the origin of the URL of the
resource being downloaded, unless that URL's scheme
component is data
, in which case let resource origin be
the same as the interface origin, if any.
If there is no interface origin, then let trusted operation be true. Otherwise, let trusted operation be true if resource origin is the same origin as interface origin, and false otherwise.
If trusted operation is true and the resource has a `Content-Disposition
` header and that header includes
filename information, then let filename have the value specified by the header, and
jump to the step labeled sanitize below. [RFC6266]
If the download was not initiated from a hyperlink created by an
a
or area
element, or if the element of the hyperlink from
which it was initiated did not have a download
attribute when the download was initiated, or if there was such an attribute but its value when
the download was initiated was the empty string, then jump to the step labeled no proposed
filename.
Let proposed filename have the value of the download
attribute of the element of the
hyperlink that initiated the download at the time the download was
initiated.
If trusted operation is true, let filename have the value of proposed filename, and jump to the step labeled sanitize below.
If the resource has a `Content-Disposition
`
header and that header specifies the attachment
disposition type, let filename have the value of proposed filename, and jump to the
step labeled sanitize below. [RFC6266]
No proposed filename: If trusted operation is true, or if the user indicated a preference for having the resource in question downloaded, let filename have a value derived from the URL of the resource in an implementation-defined manner, and jump to the step labeled sanitize below.
Let filename be set to the user's preferred filename or to a filename selected by the user agent, and jump to the step labeled sanitize below.
If the algorithm reaches this step, then a download was begun from a different origin than
the resource being downloaded, and the origin did not mark the file as suitable for
downloading, and the download was not initiated by the user. This could be because a download
attribute was used to trigger the download, or
because the resource in question is not of a type that the user agent supports.
This could be dangerous, because, for instance, a hostile server could be trying to get a user to unknowingly download private information and then re-upload it to the hostile server, by tricking the user into thinking the data is from the hostile server.
Thus, it is in the user's interests that the user be somehow notified that the resource in question comes from quite a different source, and to prevent confusion, any suggested filename from the potentially hostile interface origin should be ignored.
Sanitize: Optionally, allow the user to influence filename. For example, a user agent could prompt the user for a filename, potentially providing the value of filename as determined above as a default value.
Adjust filename to be suitable for the local file system.
For example, this could involve removing characters that are not legal in filenames, or trimming leading and trailing whitespace.
If the platform conventions do not in any way use extensions to determine the types of file on the file system, then return filename as the filename.
Let claimed type be the type given by the resource's Content-Type metadata, if any is known. Let named type be the type given by filename's extension, if any is known. For the purposes of this step, a type is a mapping of a MIME type to an extension.
If named type is consistent with the user's preferences (e.g., because the value of filename was determined by prompting the user), then return filename as the filename.
If claimed type and named type are the same type (i.e., the type given by the resource's Content-Type metadata is consistent with the type given by filename's extension), then return filename as the filename.
If the claimed type is known, then alter filename to add an extension corresponding to claimed type.
Otherwise, if named type is known to be potentially dangerous (e.g. it
will be treated by the platform conventions as a native executable, shell script, HTML
application, or executable-macro-capable document) then optionally alter filename to add a known-safe extension
(e.g. ".txt
").
This last step would make it impossible to download executables, which might not be desirable. As always, implementers are forced to balance security and usability in this matter.
Return filename as the filename.
For the purposes of this algorithm, a file extension
consists of any part of the filename that platform conventions dictate will be used for
identifying the type of the file. For example, many operating systems use the part of the filename
following the last dot (".
") in the filename to determine the type of the
file, and from that the manner in which the file is to be opened or executed.
User agents should ignore any directory or path information provided by the resource itself,
its URL, and any download
attribute, in
deciding where to store the resulting file in the user's file system.
If a hyperlink created by an a
or area
element has a
ping
attribute, and the user follows the hyperlink, and
the value of the element's href
attribute can be parsed, relative to the element's node document, without
failure, then the user agent must take the ping
attribute's value, split that string on ASCII
whitespace, parse each resulting token relative to the
element's node document, and then run these steps for each resulting URL
record ping URL, ignoring tokens that fail to parse:
If ping URL's scheme is not an HTTP(S) scheme, then return.
Optionally, return. (For example, the user agent might wish to ignore any or all ping URLs in accordance with the user's expressed preferences.)
Let request be a new request whose
URL is ping URL, method is `POST
`, body is `PING
`, client is the environment settings object of
the Document
containing the hyperlink, destination is the empty string,
credentials mode is "include
", referrer is "no-referrer
", and whose use-URL-credentials flag is set.
Let target URL be the resulting URL string obtained from parsing the value of the element's href
attribute and then:
Document
object
containing the hyperlink being audited and ping URL have the same
originDocument
containing the
hyperlink being audited is not "https
"Ping-From
` header with, as its value, the
URL of the document containing the hyperlink, and a
`Ping-To
` HTTP header with, as its value, the target URL.Ping-To
` HTTP header with, as its value,
target URL. request does not include a
`Ping-From
` header.Fetch request.
This may be done in parallel with the primary fetch, and is independent of the result of that fetch.
User agents should allow the user to adjust this behavior, for example in conjunction with a
setting that disables the sending of HTTP `Referer
` (sic)
headers. Based on the user's preferences, UAs may either ignore the ping
attribute altogether, or selectively ignore URLs in the
list (e.g. ignoring any third-party URLs); this is explicitly accounted for in the steps
above.
User agents must ignore any entity bodies returned in the responses. User agents may close the connection prematurely once they start receiving a response body.
When the ping
attribute is present, user agents
should clearly indicate to the user that following the hyperlink will also cause secondary
requests to be sent in the background, possibly including listing the actual target URLs.
For example, a visual user agent could include the hostnames of the target ping URLs along with the hyperlink's actual URL in a status bar or tooltip.
The ping
attribute is redundant with pre-existing
technologies like HTTP redirects and JavaScript in allowing web pages to track which off-site
links are most popular or allowing advertisers to track click-through rates.
However, the ping
attribute provides these advantages
to the user over those alternatives:
Thus, while it is possible to track users without this feature, authors are encouraged to use
the ping
attribute so that the user agent can make the
user experience more transparent.
Ping-From
` and `Ping-To
` headersThe `Ping-From
` and `Ping-To
` HTTP request headers are included in hyperlink
auditing requests. Their value is a URL, serialized.
Support in all current engines.
The following table summarizes the link types that are defined by this specification, by their corresponding keywords. This table is non-normative; the actual definitions for the link types are given in the next few sections.
In this section, the term referenced document refers to the resource identified by the element representing the link, and the term current document refers to the resource within which the element representing the link finds itself.
To determine which link types apply to a link
, a
, area
,
form
, or search
element,
the element's rel
attribute must be split on ASCII whitespace. The resulting tokens
are the keywords for the link types that apply to that element.
Except where otherwise specified, a keyword must not be specified more than once per rel
attribute.
Some of the sections that follow the table below list synonyms for certain keywords. The
indicated synonyms are to be handled as specified by user agents, but must
not be used in documents (for example, the keyword "copyright
").
Keywords are always ASCII case-insensitive, and must be compared as such.
Thus, rel="next"
is the same as rel="NEXT"
.
Keywords that are body-ok affect whether link
elements are
allowed in the body. The body-ok keywords are
dns-prefetch
,
modulepreload
,
pingback
,
preconnect
,
prefetch
,
preload
,
prerender
, and
stylesheet
.
New link types that are to be implemented by web browsers are to be added to this standard. The remainder can be registered as extensions.
Link type | Effect on... | body-ok | Brief description | ||
---|---|---|---|---|---|
link | a and area | form | |||
alternate | Hyperlink | not allowed | · | Gives alternate representations of the current document. | |
canonical | Hyperlink | not allowed | · | Gives the preferred URL for the current document. | |
author | Hyperlink | not allowed | · | Gives a link to the author of the current document or article. | |
bookmark | not allowed | Hyperlink | not allowed | · | Gives the permalink for the nearest ancestor section. |
dns-prefetch | External Resource | not allowed | Yes | Specifies that the user agent should preemptively perform DNS resolution for the target resource's origin. | |
external | not allowed | Annotation | · | Indicates that the referenced document is not part of the same site as the current document. | |
help | Hyperlink | · | Provides a link to context-sensitive help. | ||
icon | External Resource | not allowed | · | Imports an icon to represent the current document. | |
manifest | External Resource | not allowed | · | Imports or links to an application manifest. [MANIFEST] | |
modulepreload | External Resource | not allowed | Yes | Specifies that the user agent must preemptively fetch the module script and store it in the document's module map for later evaluation. Optionally, the module's dependencies can be fetched as well. | |
license | Hyperlink | · | Indicates that the main content of the current document is covered by the copyright license described by the referenced document. | ||
next | Hyperlink | · | Indicates that the current document is a part of a series, and that the next document in the series is the referenced document. | ||
nofollow | not allowed | Annotation | · | Indicates that the current document's original author or publisher does not endorse the referenced document. | |
noopener | not allowed | Annotation | · | Creates a top-level browsing context that is not an auxiliary
browsing context if the hyperlink would create either of those to begin with (i.e., has
an appropriate target attribute value). | |
noreferrer | not allowed | Annotation | · | No `Referer ` (sic) header will be included.
Additionally, has the same effect as noopener . | |
opener | not allowed | Annotation | · | Creates an auxiliary browsing context if the hyperlink would otherwise create
a top-level browsing context that is not an auxiliary browsing
context (i.e., has "_blank " as target attribute value). | |
pingback | External Resource | not allowed | Yes | Gives the address of the pingback server that handles pingbacks to the current document. | |
preconnect | External Resource | not allowed | Yes | Specifies that the user agent should preemptively connect to the target resource's origin. | |
prefetch | External Resource | not allowed | Yes | Specifies that the user agent should preemptively fetch and cache the target resource as it is likely to be required for a followup navigation. | |
preload | External Resource | not allowed | Yes | Specifies that the user agent must preemptively fetch and cache the target resource for current navigation according to the potential destination given by the as attribute (and the priority associated with the corresponding destination). | |
prerender | External Resource | not allowed | Yes | Specifies that the user agent should preemptively fetch the target resource and process it in a way that helps deliver a faster response in the future. | |
prev | Hyperlink | · | Indicates that the current document is a part of a series, and that the previous document in the series is the referenced document. | ||
search | Hyperlink | · | Gives a link to a resource that can be used to search through the current document and its related pages. | ||
stylesheet | External Resource | not allowed | Yes | Imports a style sheet. | |
tag | not allowed | Hyperlink | not allowed | · | Gives a tag (identified by the given address) that applies to the current document. |
alternate
"Support in one engine only.
The alternate
keyword may be used with link
,
a
, and area
elements.
The meaning of this keyword depends on the values of the other attributes.
link
element and the rel
attribute also contains the keyword stylesheet
The alternate
keyword modifies the meaning of the stylesheet
keyword in the way described for that keyword. The
alternate
keyword does not create a link of its own.
Here, a set of link
elements provide some style sheets:
<!-- a persistent style sheet -->
< link rel = "stylesheet" href = "default.css" >
<!-- the preferred alternate style sheet -->
< link rel = "stylesheet" href = "green.css" title = "Green styles" >
<!-- some alternate style sheets -->
< link rel = "alternate stylesheet" href = "contrast.css" title = "High contrast" >
< link rel = "alternate stylesheet" href = "big.css" title = "Big fonts" >
< link rel = "alternate stylesheet" href = "wide.css" title = "Wide screen" >
alternate
keyword is used with the type
attribute set to the value application/rss+xml
or the value application/atom+xml
The keyword creates a hyperlink referencing a syndication feed (though not necessarily syndicating exactly the same content as the current page).
For the purposes of feed autodiscovery, user agents should consider all link
elements in the document with the alternate
keyword used and
with their type
attribute set to the value application/rss+xml
or the value application/atom+xml
. If the user agent has the concept of a default
syndication feed, the first such element (in tree order) should be used as the
default.
The following link
elements give syndication feeds for a blog:
< link rel = "alternate" type = "application/atom+xml" href = "posts.xml" title = "Cool Stuff Blog" >
< link rel = "alternate" type = "application/atom+xml" href = "posts.xml?category=robots" title = "Cool Stuff Blog: robots category" >
< link rel = "alternate" type = "application/atom+xml" href = "comments.xml" title = "Cool Stuff Blog: Comments" >
Such link
elements would be used by user agents engaged in feed autodiscovery,
with the first being the default (where applicable).
The following example offers various different syndication feeds to the user, using
a
elements:
< p > You can access the planets database using Atom feeds:</ p >
< ul >
< li >< a href = "recently-visited-planets.xml" rel = "alternate" type = "application/atom+xml" > Recently Visited Planets</ a ></ li >
< li >< a href = "known-bad-planets.xml" rel = "alternate" type = "application/atom+xml" > Known Bad Planets</ a ></ li >
< li >< a href = "unexplored-planets.xml" rel = "alternate" type = "application/atom+xml" > Unexplored Planets</ a ></ li >
</ ul >
These links would not be used in feed autodiscovery.
The keyword creates a hyperlink referencing an alternate representation of the current document.
The nature of the referenced document is given by the hreflang
, and type
attributes.
If the alternate
keyword is used with the hreflang
attribute, and that attribute's value differs
from the document element's language, it indicates that the referenced
document is a translation.
If the alternate
keyword is used with the type
attribute, it indicates that the referenced document is
a reformulation of the current document in the specified format.
The hreflang
and type
attributes can be combined when specified with the alternate
keyword.
The following example shows how you can specify versions of the page that use alternative formats, are aimed at other languages, and that are intended for other media:
< link rel = alternate href = "/en/html" hreflang = en type = text/html title = "English HTML" >
< link rel = alternate href = "/fr/html" hreflang = fr type = text/html title = "French HTML" >
< link rel = alternate href = "/en/html/print" hreflang = en type = text/html media = print title = "English HTML (for printing)" >
< link rel = alternate href = "/fr/html/print" hreflang = fr type = text/html media = print title = "French HTML (for printing)" >
< link rel = alternate href = "/en/pdf" hreflang = en type = application/pdf title = "English PDF" >
< link rel = alternate href = "/fr/pdf" hreflang = fr type = application/pdf title = "French PDF" >
This relationship is transitive — that is, if a document links to two other documents
with the link type "alternate
", then, in addition to implying
that those documents are alternative representations of the first document, it is also implying
that those two documents are alternative representations of each other.
author
"The author
keyword may be used with link
,
a
, and area
elements. This keyword creates a hyperlink.
For a
and area
elements, the author
keyword indicates that the referenced document provides further information about the author of
the nearest article
element ancestor of the element defining the hyperlink, if there
is one, or of the page as a whole, otherwise.
For link
elements, the author
keyword indicates
that the referenced document provides further information about the author for the page as a
whole.
The "referenced document" can be, and often is, a mailto:
URL giving the email address of the author. [MAILTO]
Synonyms: For historical reasons, user agents must also treat
link
, a
, and area
elements that have a rev
attribute with the value "made
" as having the author
keyword specified as a link relationship.
bookmark
"The bookmark
keyword may be used with a
and
area
elements. This keyword creates a hyperlink.
The bookmark
keyword gives a permalink for the nearest
ancestor article
element of the linking element in question, or of the section the linking element is most closely associated with, if
there are no ancestor article
elements.
The following snippet has three permalinks. A user agent could determine which permalink applies to which part of the spec by looking at where the permalinks are given.
...
< body >
< h1 > Example of permalinks</ h1 >
< div id = "a" >
< h2 > First example</ h2 >
< p >< a href = "a.html" rel = "bookmark" > This permalink applies to
only the content from the first H2 to the second H2</ a > . The DIV isn't
exactly that section, but it roughly corresponds to it.</ p >
</ div >
< h2 > Second example</ h2 >
< article id = "b" >
< p >< a href = "b.html" rel = "bookmark" > This permalink applies to
the outer ARTICLE element</ a > (which could be, e.g., a blog post).</ p >
< article id = "c" >
< p >< a href = "c.html" rel = "bookmark" > This permalink applies to
the inner ARTICLE element</ a > (which could be, e.g., a blog comment).</ p >
</ article >
</ article >
</ body >
...
canonical
"The canonical
keyword may be used with link
element. This keyword creates a hyperlink.
The canonical
keyword indicates that URL given by the href
attribute is the preferred URL for the current document. That
helps search engines reduce duplicate content, as described in more detail in The Canonical
Link Relation. [RFC6596]
dns-prefetch
"The dns-prefetch
keyword may be used with
link
elements. This keyword creates an external
resource link. This keyword is body-ok.
The dns-prefetch
keyword indicates that preemptively
performing DNS resolution for the origin of the specified resource is likely to be
beneficial, as it is highly likely that the user will require resources located at that
origin, and the user experience would be improved by preempting the latency costs
associated with DNS resolution. User agents must implement the processing model of
the dns-prefetch
keyword described in Resource
Hints. [RESOURCEHINTS]
There is no default type for resources given by the dns-prefetch
keyword.
external
"The external
keyword may be used with a
,
area
, form
, and search
elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The external
keyword indicates that the link is leading to a
document that is not part of the site that the current document forms a part of.
help
"The help
keyword may be used with link
,
a
, area
, form
, and search
elements. This keyword creates a
hyperlink.
For a
, area
, form
, and search
elements, the help
keyword indicates that the referenced document provides further help
information for the parent of the element defining the hyperlink, and its children.
In the following example, the form control has associated context-sensitive help. The user agent could use this information, for example, displaying the referenced document if the user presses the "Help" or "F1" key.
< p >< label > Topic: < input name = topic > < a href = "help/topic.html" rel = "help" > (Help)</ a ></ label ></ p >
For link
elements, the help
keyword indicates that
the referenced document provides help for the page as a whole.
For a
and area
elements, on some browsers, the help
keyword causes the link to use a different cursor.
icon
"Support in all current engines.
The icon
keyword may be used with link
elements.
This keyword creates an external resource link.
The specified resource is an icon representing the page or site, and should be used by the user agent when representing the page in the user interface.
Icons could be auditory icons, visual icons, or other kinds of icons. If
multiple icons are provided, the user agent must select the most appropriate icon according to the
type
, media
, and sizes
attributes. If there are multiple equally appropriate icons,
user agents must use the last one declared in tree order at the time that the user
agent collected the list of icons. If the user agent tries to use an icon but that icon is
determined, upon closer examination, to in fact be inappropriate (e.g. because it uses an
unsupported format), then the user agent must try the next-most-appropriate icon as determined by
the attributes.
User agents are not required to update icons when the list of icons changes, but are encouraged to do so.
There is no default type for resources given by the icon
keyword.
However, for the purposes of determining the type of the
resource, user agents must expect the resource to be an image.
The sizes
keywords represent icon sizes in raw pixels (as
opposed to CSS pixels).
An icon that is 50 CSS pixels wide intended for displays with a device pixel density of two device pixels per CSS pixel (2x, 192dpi) would have a width of 100 raw pixels. This feature does not support indicating that a different resource is to be used for small high-resolution icons vs large low-resolution icons (e.g. 50×50 2x vs 100×100 1x).
To parse and process the attribute's value, the user agent must first split the attribute's value on ASCII whitespace, and must then parse each resulting keyword to determine what it represents.
The any
keyword represents that the
resource contains a scalable icon, e.g. as provided by an SVG image.
Other keywords must be further parsed as follows to determine what they represent:
If the keyword doesn't contain exactly one U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character, then this keyword doesn't represent anything. Return for that keyword.
Let width string be the string before the "x
" or
"X
".
Let height string be the string after the "x
" or
"X
".
If either width string or height string start with a U+0030 DIGIT ZERO (0) character or contain any characters other than ASCII digits, then this keyword doesn't represent anything. Return for that keyword.
Apply the rules for parsing non-negative integers to width string to obtain width.
Apply the rules for parsing non-negative integers to height string to obtain height.
The keyword represents that the resource contains a bitmap icon with a width of width device pixels and a height of height device pixels.
The keywords specified on the sizes
attribute must not
represent icon sizes that are not actually available in the linked resource.
The linked resource fetch setup steps for this type of linked resource, given a
link
element el and request
request, are:
Set request's destination to
"image
".
Return true.
In the absence of a link
with the icon
keyword, for
Document
objects whose URL's
scheme is an HTTP(S) scheme, user agents may
instead run these steps in parallel:
Let request be a new request whose
URL is the URL record obtained by
resolving the URL "/favicon.ico
" against the
Document
object's URL, client is the Document
object's
relevant settings object, destination is "image
",
synchronous flag is set, credentials
mode is "include
", and whose use-URL-credentials flag
is set.
Let response be the result of fetching request.
Use response's unsafe response as an icon as if it had been
declared using the icon
keyword.
The following snippet shows the top part of an application with several icons.
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > lsForums — Inbox</ title >
< link rel = icon href = favicon.png sizes = "16x16" type = "image/png" >
< link rel = icon href = windows.ico sizes = "32x32 48x48" type = "image/vnd.microsoft.icon" >
< link rel = icon href = mac.icns sizes = "128x128 512x512 8192x8192 32768x32768" >
< link rel = icon href = iphone.png sizes = "57x57" type = "image/png" >
< link rel = icon href = gnome.svg sizes = "any" type = "image/svg+xml" >
< link rel = stylesheet href = lsforums.css >
< script src = lsforums.js ></ script >
< meta name = application-name content = "lsForums" >
</ head >
< body >
...
For historical reasons, the icon
keyword may be preceded by the
keyword "shortcut
". If the "shortcut
" keyword is
present, the rel
attribute's entire value must be an
ASCII case-insensitive match for the string "shortcut icon
" (with a single U+0020 SPACE character between the tokens and
no other ASCII whitespace).
license
"The license
keyword may be used with link
,
a
, area
, form
, and search
elements. This keyword creates a
hyperlink.
The license
keyword indicates that the referenced document
provides the copyright license terms under which the main content of the current document is
provided.
This specification does not specify how to distinguish between the main content of a document and content that is not deemed to be part of that main content. The distinction should be made clear to the user.
Consider a photo sharing site. A page on that site might describe and show a photograph, and the page might be marked up as follows:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > Exampl Pictures: Kissat</ title >
< link rel = "stylesheet" href = "/style/default" >
</ head >
< body >
< h1 > Kissat</ h1 >
< nav >
< a href = "../" > Return to photo index</ a >
</ nav >
< figure >
< img src = "/pix/39627052_fd8dcd98b5.jpg" >
< figcaption > Kissat</ figcaption >
</ figure >
< p > One of them has six toes!</ p >
< p >< small >< a rel = "license" href = "http://www.opensource.org/licenses/mit-license.php" > MIT Licensed</ a ></ small ></ p >
< footer >
< a href = "/" > Home</ a > | < a href = "../" > Photo index</ a >
< p >< small > © copyright 2009 Exampl Pictures. All Rights Reserved.</ small ></ p >
</ footer >
</ body >
</ html >
In this case the license
applies to just the photo (the main
content of the document), not the whole document. In particular not the design of the page
itself, which is covered by the copyright given at the bottom of the document. This could be made
clearer in the styling (e.g. making the license link prominently positioned near the photograph,
while having the page copyright in light small text at the foot of the page).
Synonyms: For historical reasons, user agents must also treat the keyword
"copyright
" like the license
keyword.
manifest
"Support in one engine only.
The manifest
keyword may be used with link
elements.
This keyword creates an external resource link.
The manifest
keyword indicates the manifest file that provides
metadata associated with the current document.
There is no default type for resources given by the manifest
keyword.
When a web application is not installed, the appropriate time to fetch and process the linked resource for this link type is when the user agent deems it necessary. For example, when the user chooses to install the web application.
For an installed web application, the appropriate times to fetch and process the linked resource for this link type are:
When the external resource link is created on a link
element
that is already browsing-context connected.
When the external resource link's link
element becomes
browsing-context connected.
When the href
attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
In either cases, only the first link
element in tree order whose
rel
attribute contains the token manifest
may be used.
A user agent must not delay the load event for this link type.
The linked resource fetch setup steps for this type of linked resource, given a
link
element el and request
request, are:
Let context be el's node document's browsing context.
If context is null, then return false.
If context is not a top-level browsing context, then return false.
Set request's initiator to
"manifest
".
Set request's destination to
"manifest
".
Set request's mode to "cors
".
Set request's credentials
mode to the CORS settings attribute credentials mode for el's
crossorigin
content attribute.
Return true.
To process this type of linked resource given
a link
element el, boolean success, and response response:
If response's Content-Type metadata is not a JSON MIME type, then set success to false.
If success is true, then process the manifest given el and response. [MANIFEST]
modulepreload
"Support in one engine only.
The modulepreload
keyword may be used with
link
elements. This keyword creates an external resource link. This
keyword is body-ok.
The modulepreload
keyword is a specialized alternative
to the preload
keyword, with a processing model geared toward
preloading module scripts. In particular, it uses the specific
fetch behavior for module scripts (including, e.g., a different interpretation of the crossorigin
attribute), and places the result into the
appropriate module map for later evaluation. In
contrast, a similar external resource link using the preload
keyword would place the result in the preload cache, without
affecting the document's module map.
Additionally, implementations can take advantage of the fact that module scripts declare their dependencies in order to fetch the specified module's
dependency as well. This is intended as an optimization opportunity, since the user agent knows
that, in all likelihood, those dependencies will also be needed later. It will not generally be
observable without using technology such as service workers, or monitoring on the server side.
Notably, the appropriate load
or error
events will occur after the specified module is fetched, and
will not wait for any dependencies.
The appropriate times to fetch and process the linked resource for such a link are:
When the external resource link is created on a link
element
that is already browsing-context connected.
When the external resource link's link
element becomes
browsing-context connected.
When the href
attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
Unlike some other link relations, changing the relevant attributes (such as as
, crossorigin
, and
referrerpolicy
) of such a link
does not trigger a new fetch. This is because the document's module map has already been populated by a previous
fetch, and so re-fetching would be pointless.
The fetch and process the linked resource algorithm for modulepreload
links, given a link
element
el, is as follows:
If el's href
attribute's value is the
empty string, then return.
Let destination be the current state of the as
attribute (a destination), or "script
" if
it is in no state.
If destination is not script-like, then queue an element
task on the networking task source given the link
element to
fire an event named error
at the link
element, and return.
Parse a URL given el's href
attribute, relative to the element's node document. If that fails, then return.
Otherwise, let url be the resulting URL record.
Let settings object be the link
element's node
document's relevant settings object.
Let credentials mode be the CORS settings attribute credentials
mode for the crossorigin
attribute.
Let cryptographic nonce be the current value of the element's [[CryptographicNonce]] internal slot.
Let integrity metadata be the value of the integrity
attribute, if it is specified, or the empty string
otherwise.
Let referrer policy be the current state of the element's referrerpolicy
attribute.
Let options be a script fetch options whose cryptographic nonce is cryptographic
nonce, integrity metadata is
integrity metadata, parser
metadata is "not-parser-inserted
", credentials mode is credentials
mode, and referrer
policy is referrer policy.
Fetch a modulepreload module script graph given url, destination, settings object, and options. Wait until the algorithm asynchronously completes with result.
If result is null, then fire an event
named error
at the link
element, and
return.
Fire an event named load
at the link
element.
The following snippet shows the top part of an application with several modules preloaded:
<!DOCTYPE html>
< html lang = "en" >
< title > IRCFog</ title >
< link rel = "modulepreload" href = "app.mjs" >
< link rel = "modulepreload" href = "helpers.mjs" >
< link rel = "modulepreload" href = "irc.mjs" >
< link rel = "modulepreload" href = "fog-machine.mjs" >
< script type = "module" src = "app.mjs" >
...
Assume that the module graph for the application is as follows:
Here we see the application developer has used modulepreload
to declare all of the modules in their module graph,
ensuring that the user agent initiates fetches for them all. Without such preloading, the user
agent might need to go through multiple network roundtrips before discovering helpers.mjs
, if technologies such as HTTP/2 Server Push are not in play. In
this way, modulepreload
link
elements can be
used as a sort of "manifest" of the application's modules.
The following code shows how modulepreload
links can
be used in conjunction with import()
to ensure network fetching is done ahead of
time, so that when import()
is called, the module is already ready (but not
evaluated) in the module map:
< link rel = "modulepreload" href = "awesome-viewer.mjs" >
< button onclick = "import('./awesome-viewer.mjs').then(m => m.view())" >
View awesome thing
</ button >
nofollow
"The nofollow
keyword may be used with a
,
area
, form
, and search
elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The nofollow
keyword indicates that the link is not endorsed
by the original author or publisher of the page, or that the link to the referenced document was
included primarily because of a commercial relationship between people affiliated with the two
pages.
noopener
"Support in all current engines.
Support in all current engines.
The noopener
keyword may be used with a
,
area
, form
, and search
elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The keyword indicates that any newly created top-level browsing context which
results from following the hyperlink will not be an auxiliary browsing
context. E.g., its window.opener
attribute will be
null.
See also the processing model where the branching between an auxiliary browsing context and a top-level browsing context is defined.
This typically creates an auxiliary browsing context (assuming there is no
existing browsing context whose browsing context name is
"example
"):
< a href = help.html target = example > Help!</ a >
This creates a top-level browsing context that is not an auxiliary browsing context (assuming the same thing):
< a href = help.html target = example rel = noopener > Help!</ a >
These are equivalent and only navigate the parent browsing context:
< a href = index.html target = _parent > Home</ a >
< a href = index.html target = _parent rel = noopener > Home</ a >
noreferrer
"Support in all current engines.
Support in all current engines.
The noreferrer
keyword may be used with a
,
area
, form
, and search
elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
It indicates that no referrer information is to be leaked when following the link and also
implies the noopener
keyword behavior under the same
conditions.
See also the processing model where referrer is directly manipulated.
<a href="..." rel="noreferrer" target="_blank">
has the same behavior as <a href="..." rel="noreferrer noopener" target="_blank">
.
opener
"The opener
keyword may be used with a
,
area
, form
, and search
elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The keyword indicates that any newly created top-level browsing context which results from following the hyperlink will be an auxiliary browsing context.
See also the processing model.
In the following example the opener
is used to allow the help
page popup to navigate its opener, e.g., in case what the user is looking for can be found
elsewhere. An alternative might be to use a named target, rather than _blank
, but this has the potential to clash with existing names.
< a href = "..." rel = opener target = _blank > Help!</ a >
pingback
"The pingback
keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
For the semantics of the pingback
keyword, see Pingback
1.0. [PINGBACK]
preconnect
"Support in all current engines.
The preconnect
keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
The preconnect
keyword indicates that preemptively
initiating a connection to the origin of the specified resource is likely to be
beneficial, as it is highly likely that the user will require resources located at that
origin, and the user experience would be improved by preempting the latency costs
associated with establishing the connection. User agents must implement the
processing model of the preconnect
keyword described in
Resource Hints. [RESOURCEHINTS]
There is no default type for resources given by the preconnect
keyword.
prefetch
"The prefetch
keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
The prefetch
keyword indicates that preemptively fetching and caching the specified resource is likely to be
beneficial, as it is highly likely that the user will require this resource for future
navigations. User agents must implement the processing model of the prefetch
keyword described in Resource Hints.
[RESOURCEHINTS]
There is no default type for resources given by the prefetch
keyword.
preload
"Support in one engine only.
The preload
keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
The preload
keyword indicates that the user agent will
preemptively fetch and cache the specified resource according
to the potential destination given by the
as
attribute (and the priority associated with the corresponding destination), as it is highly likely that the user
will require this resource for the current navigation. [PRELOAD]
There is no default type for resources given by the preload
keyword.
A Document
has a map of preloaded resources, which is a
map, initially empty.
A preload key is a struct. It has the following items:
same-origin
", "cors
", or
"no-cors
"
A preload entry is a struct. It has the following items:
To consume a preloaded resource for Window
window,
given a URL url, a string destination, a string
mode, a string credentialsMode, a string integrityMetadata, and
onResponseAvailable, which is an algorithm accepting a response:
Let key be a preload key whose URL is url, destination is destination, integrity metadata is integrityMetadata, mode is mode, and credentials mode is credentialsMode.
Let preloads be window's associated Document
's map of
preloaded resources.
If key does not exist in preloads, then return false.
Let entry be preloads[key].
Remove preloads[key].
If entry response is null, then set entry's on response available to onResponseAvailable.
Otherwise, call onResponseAvailable with entry's response.
Return true.
The fetch and process the linked resource steps for this type of linked resource,
given a link
element el, are:
Let as be the current state of el's as
attribute.
If as does not represent a state, return false.
Let request be the result of creating a link
element request given el and the result
of translating
as.
If request is null, then return.
If as is "image
", then:
Let selected source and selected pixel density be the URL and pixel density that results from selecting an image source given el, respectively.
If selected source is null, then return false.
Parse selected source, relative to el's node document. If that fails, then return false. Otherwise, let url be the resulting URL record.
Set request's URL to url.
Let preloadKey be a preload key whose URL is request's URL, destination is request's destination, integrity metadata is request's integrity metadata, mode is request's mode, and credentials mode is request's credentials mode.
Let preloadEntry be a new preload entry.
Set el's node document's map of preloaded resources[preloadKey] to preloadEntry.
Fetch request, with processResponseEndOfBody set to the following steps given response response and null or byte sequence bytesOrNull:
If bytesOrNull is a byte sequence, then set response's body to the first return value of safely extracting bytesOrNull.
By using processResponseEndOfBody, we have extracted the entire body. This is necessary to ensure the preloader loads the entire body from the network, regardless of whether the preload will be consumed (which is uncertain at this point). This step then resets the request's body to a new body containing the same bytes, so that other specifications can read from it at the time of actual consumption, despite us having already done so once.
Otherwise, set response to a network error.
Finalize and report timing with response, given el's
relevant global object and "link
".
Fire an event named load
at el.
If preloadEntry's on response available is null, then set preloadEntry's response to response.
Otherwise, call preloadEntry's on response available with response.
prerender
"Support in one engine only.
The prerender
keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
The prerender
keyword indicates that the specified resource
might be required by the next navigation, and so it may be beneficial to not only preemptively
fetch the resource, but also to process it, e.g. by fetching its subresources or performing some rendering. User agents must implement the processing model of the prerender
keyword described in Resource Hints.
[RESOURCEHINTS]
There is no default type for resources given by the prerender
keyword.
search
"The search
keyword may be used with link
,
a
, area
, form
, and search
elements. This keyword creates a hyperlink.
The search
keyword indicates that the referenced document
provides an interface specifically for searching the document and its related resources.
OpenSearch description documents can be used with link
elements and
the search
link type to enable user agents to autodiscover search
interfaces. [OPENSEARCH]
stylesheet
"The stylesheet
keyword may be used with link
elements. This keyword creates an external resource
link that contributes to the styling processing model. This keyword is
body-ok.
The specified resource is a CSS style sheet that describes how to present the document.
If the alternate
keyword is also specified on the
link
element, then the link is an
alternative style sheet; in this case, the title
attribute
must be specified on the link
element, with a non-empty value.
The default type for resources given by the stylesheet
keyword is text/css
.
The appropriate times to fetch and process this type of link are:
When the external resource link is created on a link
element
that is already browsing-context connected.
When the external resource link's link
element becomes
browsing-context connected.
When the href
attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the disabled
attribute of the
link
element of an external resource link that is already
browsing-context connected is set, changed, or removed.
When the crossorigin
attribute of the
link
element of an external resource
link that is already browsing-context connected is set, changed, or
removed.
When the type
attribute of the link
element of an external resource link that is already browsing-context
connected is set or changed to a value that does not or no longer matches the Content-Type metadata of the previous obtained external resource, if
any.
When the type
attribute of the link
element of an external resource link that is already browsing-context
connected, but was previously not obtained due to the type
attribute specifying an unsupported type, is set, removed, or
changed.
When the external resource link that is already browsing-context connected changes from being an alternative style sheet to not being one, or vice versa.
Quirk: If the document has been set to quirks mode, has the
same origin as the URL of the external resource,
and the Content-Type metadata of the external resource is not a
supported style sheet type, the user agent must instead assume it to be text/css
.
The linked resource fetch setup steps for this type of linked resource, given a
link
element el (ignoring the request) are:
If el's disabled
attribute is set,
then return false.
If el contributes a script-blocking style sheet, increment el's node document's script-blocking style sheet counter by 1.
Return true.
See issue #968 for plans to use the CSSOM fetch a CSS style sheet algorithm instead of the default fetch and process the linked resource algorithm.
To process this type of linked resource
given a link
element el, boolean success, and response response, the user agent must run these
steps:
If the resource's Content-Type metadata is not
text/css
, then set success to false.
If el no longer creates an external resource link that contributes to the styling processing model, or if, since the resource in question was fetched, it has become appropriate to fetch it again, then return.
If el has an associated CSS style sheet, remove the CSS style sheet.
If success is true, then:
Create a CSS style sheet with the following properties:
The resulting URL string determined during the fetch and process the linked resource algorithm.
This is before any redirects get applied.
element
The media
attribute of element.
This is a reference to the (possibly absent at this time) attribute, rather than a copy of the attribute's current value. CSSOM defines what happens when the attribute is dynamically set, changed, or removed.
The title
attribute of element, if
element is in a document tree, or the empty string otherwise.
This is similarly a reference to the attribute, rather than a copy of the attribute's current value.
Set if the link is an alternative style sheet and element's explicitly enabled is false; unset otherwise.
Set if the resource is CORS-same-origin; unset otherwise.
null
Left at its default value.
Left uninitialized.
This doesn't seem right. Presumably we should be using the response body? Tracked as issue #2997.
The CSS environment encoding is the result of running the following steps: [CSSSYNTAX]
If the element has a charset
attribute, get an encoding from that attribute's value. If that
succeeds, return the resulting encoding. [ENCODING]
Otherwise, return the document's character encoding. [DOM]
Fire an event named load
at el.
Otherwise, fire an event named error
at el.
If el contributes a script-blocking style sheet, then:
Assert: el's node document's script-blocking style sheet counter is greater than 0.
Decrement el's node document's script-blocking style sheet counter by 1.
tag
"The tag
keyword may be used with a
and
area
elements. This keyword creates a hyperlink.
The tag
keyword indicates that the tag that the
referenced document represents applies to the current document.
Since it indicates that the tag applies to the current document, it would be inappropriate to use this keyword in the markup of a tag cloud, which lists the popular tags across a set of pages.
This document is about some gems, and so it is tagged with "https://en.wikipedia.org/wiki/Gemstone
" to unambiguously categorize it as applying
to the "jewel" kind of gems, and not to, say, the towns in the US, the Ruby package format, or
the Swiss locomotive class:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > My Precious</ title >
</ head >
< body >
< header >< h1 > My precious</ h1 > < p > Summer 2012</ p ></ header >
< p > Recently I managed to dispose of a red gem that had been
bothering me. I now have a much nicer blue sapphire.</ p >
< p > The red gem had been found in a bauxite stone while I was digging
out the office level, but nobody was willing to haul it away. The
same red gem stayed there for literally years.</ p >
< footer >
Tags: < a rel = tag href = "https://en.wikipedia.org/wiki/Gemstone" > Gemstone</ a >
</ footer >
</ body >
</ html >
In this document, there are two articles. The "tag
"
link, however, applies to the whole page (and would do so wherever it was placed, including if it
was within the article
elements).
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > Gem 4/4</ title >
</ head >
< body >
< article >
< h1 > 801: Steinbock</ h1 >
< p > The number 801 Gem 4/4 electro-diesel has an ibex and was rebuilt in 2002.</ p >
</ article >
< article >
< h1 > 802: Murmeltier</ h1 >
< figure >
< img src = "https://upload.wikimedia.org/wikipedia/commons/b/b0/Trains_de_la_Bernina_en_hiver_2.jpg"
alt = "The 802 was red with pantographs and tall vents on the side." >
< figcaption > The 802 in the 1980s, above Lago Bianco.</ figcaption >
</ figure >
< p > The number 802 Gem 4/4 electro-diesel has a marmot and was rebuilt in 2003.</ p >
</ article >
< p class = "topic" >< a rel = tag href = "https://en.wikipedia.org/wiki/Rhaetian_Railway_Gem_4/4" > Gem 4/4</ a ></ p >
</ body >
</ html >
Some documents form part of a sequence of documents.
A sequence of documents is one where each document can have a previous sibling and a next sibling. A document with no previous sibling is the start of its sequence, a document with no next sibling is the end of its sequence.
A document may be part of multiple sequences.
next
"The next
keyword may be used with link
,
a
, area
, form
, and search
elements. This keyword creates a hyperlink.
The next
keyword indicates that the document is part of a
sequence, and that the link is leading to the document that is the next logical document in the
sequence.
When the next
keyword is used with a link
element, user agents should implement one of the processing models described in Resource
Hints, i.e. should process such links as if they were using one of the dns-prefetch
, preconnect
,
prefetch
, or prerender
keywords. Which resource hint the user agent wishes to use is implementation-dependent; for
example, a user agent may wish to use the less-costly preconnect
hint when trying to conserve data, battery power, or
processing power, or may wish to pick a resource hint depending on heuristic analysis of past
user behavior in similar scenarios. [RESOURCEHINTS]
prev
"The prev
keyword may be used with link
,
a
, area
, form
, and search
elements. This keyword creates a hyperlink.
The prev
keyword indicates that the document is part of a
sequence, and that the link is leading to the document that is the previous logical document in
the sequence.
Synonyms: For historical reasons, user agents must also treat the keyword
"previous
" like the prev
keyword.
Extensions to the predefined set of link types may be registered on the microformats page for existing rel values. [MFREL]
Anyone is free to edit the microformats page for existing rel values at any time to add a type. Extension types must be specified with the following information:
The actual value being defined. The value should not be confusingly similar to any other defined value (e.g. differing only in case).
If the value contains a U+003A COLON character (:), it must also be an absolute URL.
link
One of the following:
link
elements.link
element; it creates a
hyperlink.link
element; it creates an external
resource link.a
and area
One of the following:
a
and area
elements.a
and area
elements; it creates a
hyperlink.a
and area
elements; it creates
an external resource link.a
and area
elements; it annotates other hyperlinks
created by the element.form
and search
One of the following:
A short non-normative description of what the keyword's meaning is.
A link to a more detailed description of the keyword's semantics and requirements. It could be another page on the wiki, or a link to an external page.
A list of other keyword values that have exactly the same processing requirements. Authors should not use the values defined to be synonyms, they are only intended to allow user agents to support legacy content. Anyone may remove synonyms that are not used in practice; only names that need to be processed as synonyms for compatibility with legacy content are to be registered in this way.
One of the following:
If a keyword is found to be redundant with existing values, it should be removed and listed as a synonym for the existing value.
If a keyword is registered in the "proposed" state for a period of a month or more without being used or specified, then it may be removed from the registry.
If a keyword is added with the "proposed" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value. If a keyword is added with the "proposed" status and found to be harmful, then it should be changed to "discontinued" status.
Anyone can change the status at any time, but should only do so in accordance with the definitions above.
Conformance checkers must use the information given on the microformats page for existing rel values to establish if a value is allowed or not: values defined in this specification or marked as "proposed" or "ratified" must be accepted when used on the elements for which they apply as described in the "Effect on..." field, whereas values marked as "discontinued" or not listed in either this specification or on the aforementioned page must be rejected as invalid. Conformance checkers may cache this information (e.g. for performance reasons or to avoid the use of unreliable network connectivity).
When an author uses a new type not defined by either this specification or the wiki page, conformance checkers should offer to add the value to the wiki, with the details described above, with the "proposed" status.
Types defined as extensions in the microformats
page for existing rel values with the status "proposed" or "ratified" may be used with the
rel
attribute on link
, a
, and area
elements in accordance to the "Effect on..." field. [MFREL]