Links

Introduction

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

Links created by <{a}>, <{area}> and <{link}> elements

The <{links/href}> attribute on <{a}> and <{area}> elements is not required; when those elements do not have <{links/href}> attributes they do not create hyperlinks. If a <{link}> element lacks the <{links/href}> attribute, then it does not define a link.

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/URL=]). It is initially null.

An element implementing the HTMLHyperlinkElementUtils mixin has an associated set the url algorithm, which sets this element's [=url/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/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/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/URL=], serialized.

The href attribute's getter must run these steps:

1. Reinitialize url.
2. Let url be this element's [=url/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/URL=] is null, return the empty string.
3. Return the Unicode serialization of this element's [=url/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/URL=] is null, return ":".
3. Return this element's [=url/URL=]'s [=url/scheme=], followed by ":".

The protocol attribute's setter must run these steps:

1. Reinitialize url.
2. If this element's [=url/URL=] is null, terminate these steps.
3. Basic URL parse the given value, followed by :", with this element's [=url/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/URL=] is null, return the empty string.
3. Return this element's [=url/URL=]'s username.

The username attribute's setter must run these steps:

1. Reinitialize url.
2. Let url be this element's [=url/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/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/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/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/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/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/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/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/URL=].
3. If url or url's host is null, url's non-relative flag is set, or url's [=url/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/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/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/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/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/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/URL=].
3. If url is null or url's [=url/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.

Following hyperlinks

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 subject 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 <{link/noopener}> keyword, and |replace| is true, then [=disowned its opener|disown target's opener=].
5. Parse the [=url/URL=] given by subject's <{links/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/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.

Downloading resources

1. Parse the [=url/URL=] given by subject's <{links/href}> attribute, relative to subject.
2. If parsing the [=url/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.

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 [=concept/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 [=concept/origin=] of the URL of the resource being downloaded, unless that URL's [=url/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 <{links/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 <{links/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/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 <{links/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.

Hyperlink auditing

If the URL of the document object containing the hyperlink being audited and the ping URL have the same origin

Or if the origins are different but the HTTPS state of the document containing the hyperlink being audited is "none"

request must include a ping-from header with the URL of the document containing the hyperlink as its value, and a ping-to HTTP header with the target URL as its value.

Otherwise

request must include a ping-to HTTP header with target URL as its value. Note: request does not include a ping-from header.

Note that currently no browser is known to offer the user an interface to manage their privacy or even learn when hyperlink auditing is taking place. So unless users have extensions to do this, the privacy benefits are still hypothetical.

Link types

So rel="next" is the same as rel="NEXT".

Link type "alternate"

If the element is a <{link}> element and the <{link/rel}> attribute also contains the keyword <{link/stylesheet}>

The <{link/alternate}> keyword modifies the meaning of the <{link/stylesheet}> keyword in the way described for that keyword. The <{link/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 <{link/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 <{link/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 <{link/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 <{link/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 <{link/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 "<{link/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.

Link type "author"

The "referenced document" can be, and often is, a mailto: URL giving the e-mail address of the author. [[RFC6068]]

Link type "bookmark"

Link type "canonical"

Link type "dns-prefetch"

Link type "external"

Link type "help"

Link type "icon"

User agents are not required to update icons when the list of icons changes, but are encouraged to do so.

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

• 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. Abort these steps 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. Abort these steps 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.

1. Let request be a new request whose [=url/URL=] is the absolute URL obtained by resolving the [=url/URL=] "/favicon.ico" against the document's [=Document/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 <{link/icon}> keyword.

Link type "license"

Link type "nofollow"

Link type "noopener"

Link type "noreferrer"

Link type "preconnect"

Link type "prefetch"

Link type "preload"

Link type "prerender"

Link type "search"

OpenSearch description documents can be used with <{link}> elements and the <{link/search}> link type to enable user agents to autodiscover search interfaces. [[!OPENSEARCH]]

Link type "stylesheet"

This is before any redirects get applied.

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.

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

Link type "tag"

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.

Sequential link types

Link type "next"

Link type "prev"

Other link types

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.

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.