W3C

HTML 5.3

Editor’s Draft,

Links are a conceptual construct, created by a, area, and link elements. They represent a connection between two resources, one of which is the current Document. There are two kinds of links in HTML:

Links to external resources
These are links to resources that are to be used to augment the current document, generally automatically processed by the user agent.
Hyperlinks
These are links to other resources that are exposed to users by the user agent. The user can cause the user agent to navigate to those resources (for example to visit them in the browser or to 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.

A hyperlink can have one or more hyperlink annotations that modify the processing semantics of that hyperlink.

The href attribute on a, area and link 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. If a link element lacks the href attribute, then it does not define a link.

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 the linked resource. The attribute may have a value; if any, it specifies the author’s recommended default file name for labeling the resource in a local file system. The author’s recommended default file name does not need to match the file name of the linked resource. 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 file names, and user agents are likely to adjust file names accordingly.

The following example shows how an image with a generated file name can be given a human-friendly default file name by the author. 
<a href="/images/IMG-d5644aBUd89z6e8.jpg" download="arranged-cakes.jpg">
  Download photo of cakes!
</a>

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 a set of space-separated tokens (keywords). 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 for a and area elements are noreferrer, and noopener. 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 a different listing of supported tokens for the link element.

Other specifications may add HTML link types as defined in Other link types, with the following additional requirements:

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.

link and a elements may also have a rev attribute, which is used to describe a reverse link relationship from the resource specified by the href to the current document. If present, the value of this attribute must be a set of space-separated tokens. Like the rel attribute, link types describes the allowed keywords and their meanings for the rev attribute. Both the rel and rev attributes may be present on the same element.

Reverse links are a way to express the reverse directional relationship of a link. In contrast to the rel attribute, whose value conveys a forward directional relationship ("how is the link related to me"), the rev attribute allows for similar relationships to be expressed in the reverse direction ("how am I related to this link"). These values can enable user agents to build a more comprehensive map of linked documents.

Given two documents, each containing a chapter of a book, the links between them could be described with the rel and rev attributes as follows:

Document with URL "chapter1.html"

<link href="chapter2.html" rel="next" rev="prev">

Document with URL "chapter2.html"

<link href="chapter1.html" rel="prev" rev="next">
<link href="chapter3.html" rel="next" rev="prev">

From chapter1.html, the link to chapter2.html is the "next" chapter in the series in the forward direction, and the "previous" chapter in the reverse direction (from chapter2.html to chapter1.html).

The links in a table of contents document might be described using rel and rev as follows: 
<ol>
  <li><a href="chapter1.html" rev="toc" rel="next">chapter 1</a></li>
  <li><a href="chapter2.html" rev="toc"></a>chapter 2</li>
  <li><a href="chapter3.html" rev="toc"></a>chapter 3</li>
</ol>

From the table of contents, the "next" logical path is to the first chapter, expressed using rel. Each chapter link has a "toc" rev value which indicates that the current document is the table of contents document for every chapter.

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 as attribute specifies the destination for a preload request for the resource given by the href attribute. If the attribute is present, the value must case-sensitively match one of the potential destination keywords. The default value is the empty string. The attribute may be omitted. The attribute must not be specified on link elements that do not have a rel attribute that contains the preload keyword. User agents must implement the processing model of the as attribute described in the Preload specification. [Preload]

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. 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]

4.8.3. API for a and area elements

[NoInterfaceObject]
interface HTMLHyperlinkElementUtils {
  stringifier attribute USVString href;
  readonly attribute USVString origin;
  attribute USVString protocol;
  attribute USVString username;
  attribute USVString password;
  attribute USVString host;
  attribute USVString hostname;
  attribute USVString port;
  attribute USVString pathname;
  attribute USVString search;
  attribute USVString hash;
};
hyperlink . toString()
hyperlink . href

Returns the hyperlink’s URL.

Can be set, to change the URL.

hyperlink . origin

Returns the hyperlink’s URL’s origin.

hyperlink . protocol

Returns the hyperlink’s URL’s scheme.

Can be set, to change the URL’s scheme.

hyperlink . username

Returns the hyperlink’s URL’s username.

Can be set, to change the URL’s username.

hyperlink . password

Returns the hyperlink’s URL’s password.

Can be set, to change the URL’s password.

hyperlink . host

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

Returns the hyperlink’s URL’s host.

Can be set, to change the URL’s host.

hyperlink . port

Returns the hyperlink’s URL’s port.

Can be set, to change the URL’s port.

hyperlink . pathname

Returns the hyperlink’s URL’s path.

Can be set, to change the URL’s path.

hyperlink . search

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

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 sets this element’s URL to the resulting URL string of parsing this element’s href content attribute value relative to this element. If parsing was aborted with an error, 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 the StructuredSerialize abstract operation.

An element implementing the HTMLHyperlinkElementUtils mixin has an associated reinitialize url algorithm, which runs these steps:

  1. If element’s URL is non-null, its scheme is "blob", and its non-relative flag is set, terminate these steps.
  2. Set the url.

To update href, set the element’s href content attribute’s value to the element’s URL, serialized.

The href attribute’s getter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url is null and this element has no href content attribute, return the empty string.
  4. Otherwise, if url is null, return this element’s href content attribute’s value.
  5. Return url, serialized.

The href attribute’s setter must set this element’s href content attribute’s value to the given value.

The origin attribute’s getter must run these steps:

  1. Reinitialize url.
  2. If this element’s URL is null, return the empty string.
  3. Return the Unicode serialization of this element’s URL's origin.

It returns the Unicode rather than the ASCII serialization for compatibility with MessageEvent.

The protocol attribute’s getter must run these steps:

  1. Reinitialize url.
  2. If this element’s URL is null, return "

    :".

  3. Return this element’s URL's scheme, followed by ":".

The protocol attribute’s setter must run these steps:

  1. Reinitialize url.
  2. If this element’s URL is null, terminate these steps.
  3. Basic URL parse the given value, followed by :", with this element’s URL as url and scheme start state as state override.
  4. Update href.

The username attribute’s getter must run these steps:

  1. Reinitialize url.
  2. If this element’s URL is null, return the empty string.
  3. Return this element’s URL's username.

The username attribute’s setter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url or url’s host is null, or url’s non-relative flag is set, terminate these steps.
  4. set the username, given url and the given value.
  5. Update href.

The password attribute’s getter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url or url’s password is null, return the empty string.
  4. Return url’s password.

The password attribute’s setter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url or url’s host is null, or url’s non-relative flag is set, terminate these steps.
  4. Set the password, given url and the given value.
  5. Update href.

The host attribute’s getter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url or url’s host is null, return the empty string.
  4. If url’s port is null, return url’s host, serialized.
  5. Return url’s host, serialized, followed by ":" and url’s port, serialized.

The host attribute’s setter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url is null or url’s non-relative flag is set, terminate these steps.
  4. Basic URL parse the given value, with url as url and host state as state override.
  5. Update href.

The hostname attribute’s getter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url or url’s host is null, return the empty string.
  4. Return url’s host, serialized.

The hostname attribute’s setter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url is null or url’s non-relative flag is set, terminate these steps.
  4. Basic URL parse the given value, with url as url and hostname state as state override.
  5. Update href.

The port attribute’s getter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url or url’s port is null, return the empty string.
  4. Return url’s port, serialized.

The port attribute’s setter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url or url’s host is null, url’s non-relative flag is set, or url’s scheme is "file", terminate these steps.
  4. Basic URL parse the given value, with url as url and port state as state override.
  5. Update href.

The pathname attribute’s getter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url is null, return the empty string.
  4. If url’s non-relative flag is set, return the first string in url’s path.
  5. Return "/", followed by the strings in url’s path (including empty strings), separated from each other by "/".

The pathname attribute’s setter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url is null or url’s non-relative flag is set, terminate these steps.
  4. Set url’s path to the empty list.
  5. Basic URL parse the given value, with url as url and path start state as state override.
  6. Update href.

The search attribute’s getter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url is null, or url’s query is either null or the empty string, return the empty string.
  4. Return "?", followed by url’s query.

The search attribute’s setter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url is null, terminate these steps.
  4. If the given value is the empty string, set url’s query to null.

  5. Otherwise, run these substeps:

    1. Let input be the given value with a single leading "?" removed, if any.
    2. Set url’s query to the empty string.
    3. Basic URL parse input, with url as url and query state as state override, and this element’s node document’s document’s character encoding as encoding override.
  6. Update href.

The hash attribute’s getter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url is null, or url’s fragment is either null or the empty string, return the empty string.
  4. Return "#", followed by url’s fragment.

The hash attribute’s setter must run these steps:

  1. Reinitialize url.
  2. Let url be this element’s URL.
  3. If url is null or url’s scheme is "javascript", terminate these steps.
  4. If the given value is the empty string, set url’s fragment to null.

  5. Otherwise, run these substeps:

    1. Let input be the given value with a single leading "#" removed, if any.
    2. Set url’s fragment to the empty string.
    3. Basic URL parse input, with url as url and fragment state as state override.
  6. Update href.

When a user follows a hyperlink created by an element subject, optionally with a hyperlink suffix, the user agent must run the following steps:

  1. Let replace be false.
  2. Let source be the browsing context that contains the Document object with which subject in question is associated.

  3. If the user indicated a specific browsing context when following the hyperlink, or if the user agent is configured to follow hyperlinks by navigating a particular browsing context, then let target be that browsing context. If this is a new top-level browsing context (e.g., when the user followed the hyperlink using "Open in New Tab"), then source must be set as the new browsing context’s one permitted sandboxed navigator.

    Otherwise, if subject is an a or area element that has a target attribute, then let target be the browsing context that is chosen by applying the rules for choosing a browsing context given a browsing context name, using the value of the target attribute as the browsing context name. If these rules result in the creation of a new browsing context, set replace to true.

    Otherwise, if target is an a or area element with no target attribute, but the Document contains a base element with a target attribute, then let target be the browsing context that is chosen by applying the rules for choosing a browsing context given a browsing context name, using the value of the target attribute of the first such base element as the browsing context name. If these rules result in the creation of a new browsing context, set replace to true.

    Otherwise, let target be the browsing context that subject itself is in.

  4. If subject’s link types include the noreferrer or noopener keyword, and replace is true, then disown target’s opener.
  5. Parse the URL given by subject’s href attribute, relative to subject’s node document.

  6. 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 a task 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 abort these steps.

  7. If there is a hyperlink suffix, append it to URL.

  8. Let resource be a new request whose url is URL and whose referrer policy is the current state of subject’s referrerpolicy content attribute.

  9. Queue a task to navigate the target browsing context to resource. If replace is true, the navigation must be performed with replacement enabled. The source browsing context must be source.

The task source for the tasks mentioned above is the DOM manipulation task source.

4.8.5. Downloading resources

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 file name 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.)

When a user downloads a hyperlink created by an element subject, optionally with a hyperlink suffix, the user agent must run the following steps:

  1. Parse the URL given by subject’s href attribute, relative to subject.
  2. 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 abort these steps.
  3. Otherwise, let URL be the resulting URL string.
  4. If there is a hyperlink suffix, append it to URL.
  5. Return to whatever algorithm invoked these steps and continue these steps in parallel.
  6. Fetch URL and handle the resulting resource 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; or otherwise should report any problems downloading the file to the user.

If the user agent needs a file name 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.

  1. Let filename be the void value.
  2. If the resource has a Content-Disposition header, that header specifies the attachment disposition type, and the header includes file name information, then let filename have the value specified by the header, and jump to the step labeled sanitize below. [RFC6266]
  3. Let interface origin be the origin of the Document in which the download or navigate action resulting in the download was initiated, if any.
  4. 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.
  5. 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.
  6. If trusted operation is true and the resource has a Content-Disposition header and that header includes file name information, then let filename have the value specified by the header, and jump to the step labeled sanitize below. [RFC6266]
  7. 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 file name.
  8. 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.
  9. If trusted operation is true, let filename have the value of proposed filename, and jump to the step labeled sanitize below.
  10. 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]
  11. No proposed file name: 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 a user-agent-defined manner, and jump to the step labeled sanitize below.

  12. Act in a user-agent-defined manner to safeguard the user from a potentially hostile cross-origin download. If the download is not to be aborted, then let filename be set to the user’s preferred file name or to a file name 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 file name from the potentially hostile interface origin should be ignored.

  13. Sanitize: Optionally, allow the user to influence filename. For example, a user agent could prompt the user for a file name, potentially providing the value of filename as determined above as a default value.

  14. Adjust filename to be suitable for the local file system.

    For example, this could involve removing characters that are not legal in file names, or trimming leading and trailing white space.

  15. 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 file name and abort these steps.
  16. 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.
  17. 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 file name and abort these steps.
  18. 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 file name and abort these steps.

  19. 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, implementors are forced to balance security and usability in this matter.

  20. Return filename as the file name.

For the purposes of this algorithm, a file extension consists of any part of the file name that platform conventions dictate will be used for identifying the type of the file. For example, many operating systems use the part of the file name following the last dot (".") in the file name 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 whose href attribute can be parsed relative to the element’s node document without failure, and the user follows the hyperlink, then the user agent must take the ping attribute’s value, split that string on spaces, parse each resulting token relative to the element’s node document, then run these steps for each resulting URL record ping URL (ignoring tokens that fail to parse):

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 alter this behavior. For example, in conjunction with a setting that disables the sending of HTTP referrer (sic) headers. Based on the user’s preferences, user agents may ignore the ping attribute completely, or selectively ignore URLs (for example 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 make it clear to the user that following the hyperlink will also cause secondary requests to be sent in the background.

For example, a user agent could visually display the host names of the target ping URLs, and the hyperlink’s actual URL, in a 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 over those alternatives:

  • It allows the user to see the unobscured final target URL.

  • It allows the user agent to inform the user about out-of-band notifications.

  • It allows the user to disable notifications without losing the underlying functionality.

  • It allows the user agent to optimize the use of available bandwidth, so the target page loads faster.

So while it is possible to track users without this feature, authors are encouraged to use the ping attribute, so the user agent can make the experience more transparent.

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, or area element, the element’s rel attribute must be split on spaces. 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.

So 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 defined by this specification are dns-prefetch, preconnect, prefetch, preload, prerender, and stylesheet.

Other applicable specifications may define body-ok keywords.

Link type Effect on... body-ok Brief description
link a and area
alternate hyperlink hyperlink · Gives alternate representations of the current document.
author hyperlink hyperlink · Gives a link to the author of the current document or article.
bookmark not allowed hyperlink · Gives the permalink for the nearest ancestor section.
dns-prefetch not allowed hyperlink Yes Gives the origin for resources so the User Agent can resolve it as early as possible.
external not allowed Annotation · Indicates that the referenced document is not part of the same site as the current document.
help hyperlink hyperlink · Provides a link to context-sensitive help.
icon External Resource not allowed · Imports an icon to represent the current document.
license hyperlink hyperlink · Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
next hyperlink 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 · Requires that any browsing context created by following the hyperlink to disown its opener.
noreferrer not allowed Annotation · Requires that the user agent not send an HTTP Referer (sic) header if the user follows the hyperlink.
preconnect External Resource not allowed Yes Specifies that the target resource should be preemptively cached and cache the target resource as it is likely to be required for a followup navigation.
prefetch External Resource not allowed Yes Specifies that the target resource should be preemptively cached and cache the target resource as it is likely to be required for a followup navigation.
prerender 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 target resource should be preemptively cached and cache the target resource as it is likely to be required for a followup navigation.
prev hyperlink 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 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 stylesheet.
tag not allowed hyperlink · Gives a tag (identified by the given address) that applies to the current document.

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.

If the element is a 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.

A document does not need to have a single style sheet. It can have a default style and any number of alternatives for the reader to choose from. In the following example, a set of link elements provide some alternate style sheets: 
<!-- a persistent style sheet -->
<link rel="stylesheet" href="default.css">

<!-- 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">

How the user can select the alternate style sheets will depend on the browser. Not all browsers offer a user interface for selecting style sheets.

If the 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).

The first link or a element in the document (in tree order) with the alternate keyword used with the type attribute set to the value application/rss+xml or the value application/atom+xml must be treated as the default syndication feed for the purposes of feed autodiscovery.

The following link element gives the syndication feed for the current page: 
<link rel="alternate" type="application/atom+xml" href="data.xml">

The following extract offers various different syndication feeds:

<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>
Otherwise

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.

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 e-mail address of the author. [RFC6068]

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.

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>
Link type "dns-prefetch"

The dns-prefetch keyword may be used with link.This keyword is body-ok.

The dns-prefetch keyword is used to indicate an origin that will be used to fetch required resources, and that the user agent SHOULD resolve as early as possible.

See [resource-hints] for full definition.

The external keyword may be used with a, and area elements. This keyword creates a hyperlink. The external keyword indicates that the referenced document is not part of the same site as the current document. It is informational, and requires no specific browser behaviour.

The help keyword may be used with link, a, and area elements. This keyword creates a hyperlink.

For a and area 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.

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 keyword 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 spaces, 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:

The keywords specified on the sizes attribute must not represent icon sizes that are not actually available in the linked resource.

In the absence of a link with the icon keyword, for Document objects obtained over HTTP or HTTPS, user agents may instead run these steps in parallel:

  1. Let request be a new request whose URL is the absolute URL obtained by resolving the URL "/favicon.ico" against the document’s URL, client is the Document object’s Window object’s environment settings object, type is "image", destination is "subresource", synchronous flag is set, credentials mode is "include", and whose use-URL-credentials flag is set.
  2. Let response be the result of fetching request.
  3. 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>
  <head>
    <title>Example</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="favicon.svg" sizes="any" type="image/svg+xml">
  </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 space characters).

The license keyword may be used with link, a, and area 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 defines the main content of a document and content that is not deemed to be part of that main content via the main element. 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: 
...
<main>
  <figure>
    <img src="/pix/39627052_fd8dcd98b5.jpg">
    <figcaption>My Cats</figcaption>
  </figure>
  <p>One of them has six toes!</p>
  <p><small>This photograph is <a rel="license" href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Licensed (CC BY 4.0)</a></small></p>
</main>
<footer>
  <p><small>© copyright Example Pictures. All Rights Reserved.</small></p>
</footer>
...

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 should be made clear in the text referencing the licensing link and could also be made clearer in the styling (e.g., making the license link prominently positioned near the photograph, while having the page copyright in small text at the foot of the page, or adding a border to the main element.)

Synonyms: For historical reasons, user agents must also treat the keyword "copyright" like the license keyword.

The nofollow keyword may be used with a and area 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.

The noopener keyword may be used with a and area 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 browsing context which results from following the hyperlink will have disowned its opener, which means that its window.opener property will be null.

The noreferrer keyword may be used with a and area 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.

If a user agent follows a link defined by an a or area element that has the noreferrer keyword, the user agent must set their request’s referrer to "no-referrer".

For historical reasons, the noreferrer keyword implies the behavior associated with the noopener keyword when present on a hyperlink that creates a new browsing context.
That is:
<a href="..." rel="noreferrer" target="_blank">
has the same behavior as:
<a href="..." rel="noreferrer noopener" target="_blank">

The preconnect keyword may be used with link.This keyword is body-ok.

The preconnect keyword is used to initiate an early connection, which includes the DNS lookup, TCP handshake, and optional TLS negotiation, allows the user agent to mask the high latency costs of establishing a connection.

See [resource-hints] for full definition.

The prefetch keyword may be used with link. This keyword creates an external resource link. This keyword is body-ok.

The prefetch keyword is used to identify a resource that might be required by the next navigation, and that the user agent SHOULD fetch, such that the user agent can deliver a faster response once the resource is requested in the future.

See [resource-hints] for full definition.

The preload keyword may be used with link. This keyword creates an external resource link. This keyword is body-ok.

The preload keyword indicates that the user agent must 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 current navigation. User agents must implement the processing model of the preload keyword described in the Preload specification. [Preload]

There is no default type for resources given by the preload keyword.

The prerender keyword may be used with link. This keyword creates an external resource link. This keyword is body-ok.

The prerender keyword identifies a resource that might be required by the next navigation from the link context, and that the user agent ought to fetch and execute, such that the user agent can deliver a faster response once the resource is requested in the future.

See [resource-hints] for full definition.

The search keyword may be used with link, a, and area 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]

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 resource that describes how to present the document. Exactly how the resource is to be processed depends on the actual type of the resource.

If the alternate keyword is also specified on the link element, then the link is an alternative stylesheet; 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 obtain the resource are:

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.

Once a resource has been obtained, if its Content-Type metadata is text/css, the user agent must run these steps:

  1. Let element be the link element that created the external resource link.

  2. If element has an associated CSS style sheet, remove the CSS style sheet in question.

  3. If element no longer creates an external resource link that contributes to the styling processing model, or if, since the resource in question was obtained, it has become appropriate to obtain it again (meaning this algorithm is about to be invoked again for a newly obtained resource), then abort these steps.

  4. Create a CSS style sheet with the following properties:

    type

    text/css

    location

    The resulting URL string determined during the obtain algorithm.

    This is before any redirects get applied.

    owner node

    element

    media

    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. The CSSOM specification defines what happens when the attribute is dynamically set, changed, or removed.

    title

    The title attribute of element.

    This is similarly a reference to the attribute, rather than a copy of the attribute’s current value.

    alternate flag

    Set if the link is an alternative stylesheet; unset otherwise.

    origin-clean flag

    Set if the resource is CORS-same-origin; unset otherwise.

    parent CSS style sheet
    owner CSS rule

    null

    disabled flag

    Left at its default value.

    CSS rules

    Left uninitialized.

    The CSS environment encoding is the result of running the following steps: [CSS-SYNTAX-3]

    1. If the element has a charset attribute, get an encoding from that attribute’s value. If that succeeds, return the resulting encoding and abort these steps. [ENCODING]

    2. Otherwise, return the document’s character encoding. [DOM]

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. It is tagged with "https://en.wikipedia.org/wiki/Gemstone" to unambiguously categorize it as applying to the "jewel" kind of gems. 
<body>
  <p>Recently I managed to dispose of a red gem that had been bothering me. I now have a much nicer blue sapphire.</p>
  <footer>
    Tags: <a rel="tag" href="https://en.wikipedia.org/wiki/Gemstone">Gemstone</a>
  </footer>
</body>
In this document there are two articles. The "tag" link applies to the whole page. It will do so wherever it is placed, including if it is within the article elements). 
<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>
    <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>

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.

The next keyword may be used with link, a, and area 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.

The prev keyword may be used with link, a, and area 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 in the HTML link extensions section of the microformats wiki existing-rel-values page [MFREL], or filed as an issue on this specification.

Proposed extension types should be specified with the following information:

Keyword

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.

Effect on... link

One of the following:

Not allowed
The keyword must not be specified on link elements.
Hyperlink
The keyword may be specified on a link element; it creates a hyperlink.
External Resource
The keyword may be specified on a link element; it creates an external resource link.
Effect on... a and area

One of the following:

Not allowed
The keyword must not be specified on a and area elements.
Hyperlink
The keyword may be specified on a and area elements; it creates a hyperlink.
External Resource
The keyword may be specified on a and area elements; it creates an external resource link.
Hyperlink Annotation
The keyword may be specified on a and area elements; it annotates other hyperlinks created by the element.
Brief description
A short non-normative description of what the keyword’s meaning is.
Specification
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.
Synonyms
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.
Status

One of the following:

Proposed
The keyword has not received wide peer review and approval. Someone has proposed it and is, or soon will be, using it.
Ratified
The keyword has received wide peer review and approval. It has a specification that unambiguously defines how to handle pages that use the keyword, including when they use it in incorrect ways.
Discontinued
The keyword has received wide peer review and it has been found wanting. Existing pages are using this keyword, but new pages should avoid it. The "brief description" and "specification" entries will give details of what authors should use instead, if anything.

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 may use the information given on the microformats wiki existing-rel-values page 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 values not containing a U+003A COLON character but not listed in either this specification or on the aforementioned page must be reported as invalid. The remaining values must be accepted as valid if they are absolute URLs containing US-ASCII characters only and rejected otherwise. Conformance checkers may cache this information (e.g., for performance reasons or to avoid the use of unreliable network connectivity).

Note: Even URL-valued link types are compared ASCII-case-insensitively. Validators might choose to warn about characters U+0041 (LATIN CAPITAL LETTER A) through U+005A (LATIN CAPITAL LETTER Z) (inclusive) in the pre-case-folded form of link types that contain a colon.

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 wiki existing-rel-values page 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]

← 4.7 Embedded content — Table of contents — 4.9 Tabular data →