<link>: The External Resource Link element #

::: section-content The <link> HTML element specifies relationships between the current document and an external resource. This element is most commonly used to link to stylesheets, but is also used to establish site icons (both "favicon" style icons and icons for the home screen and apps on mobile devices) among other things. :::

Try it #

::: section-content ::: iframe ::: {.output-header .border-rounded-top}

HTML Demo: <link> #

Reset :::

::: {#warning-no-script .warning-container} ::: warning The interactive example cannot be shown because JavaScript is disabled. ::: :::

::: {#warning-mathml-not-supported .warning-container .hidden} ::: warning The interactive example cannot be shown because MathML is not supported by your browser. ::: :::

::: {#editor-container .editor-container .tabbed-shorter .hidden .border-rounded-bottom editor-type=“tabbed”} ::: {#tab-container .section .tabs} ::: {#tablist .tab-list role=“tablist”} HTML

CSS

JavaScript :::

::: {#html-panel .section .hidden tabindex=“0” role=“tabpanel” aria-labelledby=“html” aria-hidden=“true”} ::: {#html-editor}

<p>This text will be red as defined in the external stylesheet.</p>
<p style="color: blue">The <code>style</code> attribute can override it, though.</p>

::: :::

::: {#css-panel .section .hidden tabindex=“0” role=“tabpanel” aria-labelledby=“css” aria-hidden=“true”} ::: {#css-editor} ::: :::

::: {#js-panel .section .hidden tabindex=“0” role=“tabpanel” aria-labelledby=“js” aria-hidden=“true”} ::: {#js-editor} ::: ::: :::

::: {#output .output-container}

Output #

::: :::

::: {.section .console-container .hidden aria-hidden=“true”}

Console Output #

![] clear console

::: {#console .console} ::: :::

::: {#html-output .output .editor-tabbed} %html-content% ::: :::

To link an external stylesheet, you'd include a <link> element inside your <head> like this:

::: code-example [html]{.language-name}

<link href="main.css" rel="stylesheet" />

:::

This simple example provides the path to the stylesheet inside an href attribute, and a rel attribute with a value of stylesheet. The rel stands for "relationship", and is one of the key features of the <link> element — the value denotes how the item being linked to is related to the containing document.

There are a number of other common types you'll come across. For example, a link to the site's favicon:

::: code-example [html]{.language-name}

<link rel="icon" href="favicon.ico" />

:::

There are a number of other icon rel values, mainly used to indicate special icon types for use on various mobile platforms, e.g.:

::: code-example [html]{.language-name}

<link
  rel="apple-touch-icon"
  sizes="114x114"
  href="apple-icon-114.png"
  type="image/png" />

:::

The sizes attribute indicates the icon size, while the type contains the MIME type of the resource being linked. These provide useful hints to allow the browser to choose the most appropriate icon available.

You can also provide a media type or query inside a media attribute; this resource will then only be loaded if the media condition is true. For example:

::: code-example [html]{.language-name}

<link href="print.css" rel="stylesheet" media="print" />
<link
  href="mobile.css"
  rel="stylesheet"
  media="screen and (max-width: 600px)" />

:::

Some interesting new performance and security features have been added to the <link> element too. Take this example:

::: code-example [html]{.language-name}

<link
  rel="preload"
  href="myFont.woff2"
  as="font"
  type="font/woff2"
  crossorigin="anonymous" />

:::

A rel value of preload indicates that the browser should preload this resource (see rel="preload" for more details), with the as attribute indicating the specific class of content being fetched. The crossorigin attribute indicates whether the resource should be fetched with a CORS request.

Other usage notes:

A <link> element can occur either in the <head> or <body> element, depending on whether it has a link type{target="_blank"} that is body-ok. For example, the stylesheet link type is body-ok, and therefore <link rel="stylesheet"> is permitted in the body. However, this isn't a good practice to follow; it makes more sense to separate your <link> elements from your body content, putting them in the <head>.
When using <link> to establish a favicon for a site, and your site uses a Content Security Policy (CSP) to enhance its security, the policy applies to the favicon. If you encounter problems with the favicon not loading, verify that the Content-Security-Policy header's img-src directive is not preventing access to it.
The HTML and XHTML specifications define event handlers for the <link> element, but it is unclear how they would be used.
Under XHTML 1.0, void elements such as <link> require a trailing slash: <link />.
WebTV supports the use of the value next for rel to preload the next page in a document series. :::

Attributes #

::: section-content This element includes the global attributes.

as

This attribute is required when rel="preload" has been set on the <link> element, optional when rel="modulepreload" has been set, and otherwise should not be used. It specifies the type of content being loaded by the <link>, which is necessary for request matching, application of correct content security policy, and setting of correct Accept request header.

Furthermore, rel="preload" uses this as a signal for request prioritization. The table below lists the valid values for this attribute and the elements or resources they apply to.

Value	Applies To
audio	`<audio>` elements
document	`<iframe>` and `<frame>` elements
embed	`<embed>` elements
fetch	fetch, XHR Note: This value also requires `<link>` to contain the crossorigin attribute, see CORS-enabled fetches.
font	CSS @font-face
image	`<img>` and `<picture>` elements with srcset or imageset attributes, SVG `<image>` elements, CSS `*-image` rules
object	`<object>` elements
script	`<script>` elements, Worker `importScripts`
style	`<link rel=stylesheet>` elements, CSS `@import`
track	`<track>` elements
video	`<video>` elements
worker	Worker, SharedWorker

blocking [Experimental]{.visually-hidden}

This attribute explicitly indicates that certain operations should be blocked on the fetching of an external resource. The operations that are to be blocked must be a space-separated list of blocking attributes listed below.

render: The rendering of content on the screen is blocked.

crossorigin

This enumerated attribute indicates whether CORS must be used when fetching the resource. CORS-enabled images can be reused in the <canvas> element without being tainted. The allowed values are:

anonymous: A cross-origin request (i.e. with an Origin HTTP header) is performed, but no credential is sent (i.e. no cookie, X.509 certificate, or HTTP Basic authentication). If the server does not give credentials to the origin site (by not setting the Access-Control-Allow-Origin HTTP header) the resource will be tainted and its usage restricted.
use-credentials: A cross-origin request (i.e. with an Origin HTTP header) is performed along with a credential sent (i.e. a cookie, certificate, and/or HTTP Basic authentication is performed). If the server does not give credentials to the origin site (through Access-Control-Allow-Credentials HTTP header), the resource will be tainted and its usage restricted.

If the attribute is not present, the resource is fetched without a CORS request (i.e. without sending the Origin HTTP header), preventing its non-tainted usage. If invalid, it is handled as if the enumerated keyword anonymous was used. See CORS settings attributes for additional information.

disabled [Non-standard]{.visually-hidden}

For rel="stylesheet" only, the disabled Boolean attribute indicates whether the described stylesheet should be loaded and applied to the document. If disabled is specified in the HTML when it is loaded, the stylesheet will not be loaded during page load. Instead, the stylesheet will be loaded on-demand, if and when the disabled attribute is changed to false or removed.

Setting the disabled property in the DOM causes the stylesheet to be removed from the document's Document.styleSheets list.

fetchpriority [Experimental]{.visually-hidden}

Provides a hint of the relative priority to use when fetching a preloaded resource. Allowed values:

high: Signals a high-priority fetch relative to other resources of the same type.
low: Signals a low-priority fetch relative to other resources of the same type.
auto: Default: Signals automatic determination of fetch priority relative to other resources of the same type.

href

This attribute specifies the URL of the linked resource. A URL can be absolute or relative.

hreflang

This attribute indicates the language of the linked resource. It is purely advisory. Allowed values are specified by RFC 5646: Tags for Identifying Languages (also known as BCP 47){target="_blank"}. Use this attribute only if the href attribute is present.

imagesizes

For rel="preload" and as="image" only, the imagesizes attribute is a sizes attribute{target="_blank"} that indicates to preload the appropriate resource used by an img element with corresponding values for its srcset and sizes attributes.

imagesrcset

For rel="preload" and as="image" only, the imagesrcset attribute is a sourceset attribute{target="_blank"} that indicates to preload the appropriate resource used by an img element with corresponding values for its srcset and sizes attributes.

integrity

Contains inline metadata — a base64-encoded cryptographic hash of the resource (file) you're telling the browser to fetch. The browser can use this to verify that the fetched resource has been delivered free of unexpected manipulation. See Subresource Integrity.

media

This attribute specifies the media that the linked resource applies to. Its value must be a media type / media query. This attribute is mainly useful when linking to external stylesheets — it allows the user agent to pick the best adapted one for the device it runs on.

::: {#sect2 .notecard .note} Note:

In HTML 4, this can only be a simple white-space-separated list of media description literals, i.e., media types and groups, where defined and allowed as values for this attribute, such as print, screen, aural, braille. HTML5 extended this to any kind of media queries, which are a superset of the allowed values of HTML 4.
Browsers not supporting CSS Media Queries won't necessarily recognize the adequate link; do not forget to set fallback links, the restricted set of media queries defined in HTML 4. :::

referrerpolicy

A string indicating which referrer to use when fetching the resource:

no-referrer means that the Referer header will not be sent.
no-referrer-when-downgrade means that no Referer header will be sent when navigating to an origin without TLS (HTTPS). This is a user agent's default behavior, if no policy is otherwise specified.
origin means that the referrer will be the origin of the page, which is roughly the scheme, the host, and the port.
origin-when-cross-origin means that navigating to other origins will be limited to the scheme, the host, and the port, while navigating on the same origin will include the referrer's path.
unsafe-url means that the referrer will include the origin and the path (but not the fragment, password, or username). This case is unsafe because it can leak origins and paths from TLS-protected resources to insecure origins.

rel

This attribute names a relationship of the linked document to the current document. The attribute must be a space-separated list of link type values.

sizes [Experimental]{.visually-hidden}

This attribute defines the sizes of the icons for visual media contained in the resource. It must be present only if the rel contains a value of icon or a non-standard type such as Apple's apple-touch-icon. It may have the following values:

any, meaning that the icon can be scaled to any size as it is in a vector format, like image/svg+xml.
a white-space separated list of sizes, each in the format <width in pixels>x<height in pixels> or <width in pixels>X<height in pixels>. Each of these sizes must be contained in the resource.

::: {#sect3 .notecard .note} Note: Most icon formats are only able to store one single icon; therefore, most of the time, the sizes attribute contains only one entry. MS's ICO format does, as well as Apple's ICNS. ICO is more ubiquitous, so you should use this format if cross-browser support is a concern (especially for old IE versions). :::

title

The title attribute has special semantics on the <link> element. When used on a <link rel="stylesheet"> it defines a default or an alternate stylesheet.

type

This attribute is used to define the type of the content linked to. The value of the attribute should be a MIME type such as text/html, text/css, and so on. The common use of this attribute is to define the type of stylesheet being referenced (such as text/css), but given that CSS is the only stylesheet language used on the web, not only is it possible to omit the type attribute, but is actually now recommended practice. It is also used on rel="preload" link types, to make sure the browser only downloads file types that it supports. :::

Non-standard attributes #

::: section-content

methods [Non-standard]{.visually-hidden} [Deprecated]{.visually-hidden}: The value of this attribute provides information about the functions that might be performed on an object. The values generally are given by the HTTP protocol when it is used, but it might (for similar reasons as for the title attribute) be useful to include advisory information in advance in the link. For example, the browser might choose a different rendering of a link as a function of the methods specified; something that is searchable might get a different icon, or an outside link might render with an indication of leaving the current site. This attribute is not well understood nor supported, even by the defining browser, Internet Explorer 4.
target [Deprecated]{.visually-hidden}: Defines the frame or window name that has the defined linking relationship or that will show the rendering of any linked resource. :::

Obsolete attributes #

::: section-content

charset [Deprecated]{.visually-hidden}

This attribute defines the character encoding of the linked resource. The value is a space- and/or comma-delimited list of character sets as defined in RFC 2045{target="_blank"}. The default value is iso-8859-1.

::: {#sect4 .notecard .note} Note: To produce the same effect as this obsolete attribute, use the Content-Type HTTP header on the linked resource. :::

rev [Deprecated]{.visually-hidden}

The value of this attribute shows the relationship of the current document to the linked document, as defined by the href attribute. The attribute thus defines the reverse relationship compared to the value of the rel attribute. Link type values for the attribute are similar to the possible values for rel.

::: {#sect5 .notecard .note} Note: Instead of rev, you should use the rel attribute with the opposite link type value. For example, to establish the reverse link for made, specify author. Also, this attribute doesn't stand for "revision" and must not be used with a version number, even though many sites misuse it in this way. ::: :::

Examples #

Including a stylesheet #

::: section-content To include a stylesheet in a page, use the following syntax:

::: code-example [html]{.language-name}

<link href="style.css" rel="stylesheet" />

::: :::

Providing alternative stylesheets #

::: section-content You can also specify alternative style sheets.

The user can choose which style sheet to use by choosing it from the View > Page Style menu. This provides a way for users to see multiple versions of a page.

::: code-example [html]{.language-name}

<link href="default.css" rel="stylesheet" title="Default Style" />
<link href="fancy.css" rel="alternate stylesheet" title="Fancy" />
<link href="basic.css" rel="alternate stylesheet" title="Basic" />

::: :::

Providing icons for different usage contexts #

::: section-content You can include links to several icons on the same page, and the browser will choose which one works best for its particular context using the rel and sizes values as hints.

::: code-example [html]{.language-name}

<!-- third-generation iPad with high-resolution Retina display: -->
<link rel="apple-touch-icon" sizes="144x144" href="favicon144.png" />
<!-- iPhone with high-resolution Retina display: -->
<link rel="apple-touch-icon" sizes="114x114" href="favicon114.png" />
<!-- first- and second-generation iPad: -->
<link rel="apple-touch-icon" sizes="72x72" href="favicon72.png" />
<!-- non-Retina iPhone, iPod Touch, and Android 2.1+ devices: -->
<link rel="apple-touch-icon" href="favicon57.png" />
<!-- basic favicon -->
<link rel="icon" href="favicon32.png" />

::: :::

Conditionally loading resources with media queries #

::: section-content You can provide a media type or query inside a media attribute; this resource will then only be loaded if the media condition is true. For example:

::: code-example [html]{.language-name}

<link href="print.css" rel="stylesheet" media="print" />
<link href="mobile.css" rel="stylesheet" media="all" />
<link
  href="desktop.css"
  rel="stylesheet"
  media="screen and (min-width: 600px)" />
<link
  href="highres.css"
  rel="stylesheet"
  media="screen and (min-resolution: 300dpi)" />

::: :::

Stylesheet load events #

::: section-content You can determine when a style sheet has been loaded by watching for a load event to fire on it; similarly, you can detect if an error has occurred while processing a style sheet by watching for an error event:

::: code-example [html]{.language-name}

<script>
  const stylesheet = document.querySelector("#my-stylesheet");

  stylesheet.onload = () => {
    // Do something interesting; the sheet has been loaded
  };

  stylesheet.onerror = () => {
    console.log("An error occurred loading the stylesheet!");
  };
</script>

<link rel="stylesheet" href="mystylesheet.css" id="my-stylesheet" />

:::

::: {#sect6 .notecard .note} Note: The load event fires once the stylesheet and all of its imported content has been loaded and parsed, and immediately before the styles start being applied to the content. ::: :::

Preload examples #

::: section-content You can find a number of <link rel="preload"> examples in Preloading content with rel="preload". :::

Blocking rendering till a resource is fetched #

::: section-content You can include render token inside a blocking attribute; the rendering of the page will be blocked till the resource is fetched. For example:

::: code-example [html]{.language-name}

<link blocking="render" href="critical-font.woff2" as="font" />

::: :::

Technical summary #

::: section-content

Content categories	Metadata content. If `itemprop` is present: Flow content and phrasing content.
Permitted content	None; it is a void element.
Tag omission	As it is a void element, the start tag must be present and the end tag must not be present
Permitted parents	Any element that accepts metadata elements. If itemprop is present: any element that accepts phrasing content.
Implicit ARIA role	`link` with `href` attribute
Permitted ARIA roles	No `role` permitted
DOM interface	`HTMLLinkElement`

:::

Specifications #

::: _table #

Specification #

HTML Standard
[# the-link-element]{.small}

:::

Browser compatibility #

::: _table #

                 Desktop                                                                                                            Mobile

                 Chrome                    Edge                      Firefox         Internet   Opera                     Safari    WebView Android           Chrome Android            Firefox for     Opera Android             Safari   Samsung Internet
                                                                                     Explorer                                                                                           Android                                   on IOS

link 1 12 1 Yes ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0

blocking 105 105 No No 91 No 105 105 No 72 No 20.0

charset 1 12 1 ≤6 ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0

crossorigin 34 17 18 No 21 10 37 34 18 21 10 2.0

                                                                     Before Firefox                                                                                                     Before Firefox                                     
                                                                     83,                                                                                                                83,                                                
                                                                     `crossorigin`                                                                                                      `crossorigin`                                      
                                                                     is not                                                                                                             is not                                             
                                                                     supported for                                                                                                      supported for                                      
                                                                     `rel="icon"`.                                                                                                      `rel="icon"`.

disabled 1 12 1 ≤6 ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0

                 In Chrome and other       Since Edge 79, adding the                            In Chrome and other                 In Chrome and other       In Chrome and other                       In Chrome and other                In Samsung Internet and
                 Blink-based browsers,     `disabled` attribute                                 Blink-based browsers,               Blink-based browsers,     Blink-based browsers,                     Blink-based browsers,              other Blink-based
                 adding the `disabled`     using JavaScript does not                            adding the `disabled`               adding the `disabled`     adding the `disabled`                     adding the `disabled`              browsers, adding the
                 attribute using           remove the stylesheet                                attribute using                     attribute using           attribute using                           attribute using                    `disabled` attribute
                 JavaScript does not       from                                                 JavaScript does not                 JavaScript does not       JavaScript does not                       JavaScript does not                using JavaScript does not
                 remove the stylesheet     `document.styleSheets`.                              remove the stylesheet               remove the stylesheet     remove the stylesheet                     remove the stylesheet              remove the stylesheet
                 from                                                                           from                                from                      from                                      from                               from
                 `document.styleSheets`.                                                        `document.styleSheets`.             `document.styleSheets`.   `document.styleSheets`.                   `document.styleSheets`.            `document.styleSheets`.

fetchpriority 101 101 No No No preview 101 101 No 70 No 19.0

href 1 12 1 ≤6 ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0

hreflang 1 12 1 ≤6 ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0

imagesizes 73 79 78 No 60 No 73 73 79 52 No 11.0

imagesrcset 73 79 78 No 60 No 73 73 79 52 No 11.0

integrity 45 17 43 No 32 11.1 45 45 43 32 11.3 5.0

media 1 12 1 ≤6 ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0

methods No 12–79 No 4 No No No No No No No No

referrerpolicy 51 79 50 No 38 14 51 51 50 41 14 7.2

rel 1 12 1 Yes 9 1 4.4 18 4 10.1 1 1.0

rev 1 12 1 ≤6 ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0

sizes ≤80 80 ≤72 No 67 6 80 80 79 57 6 13.0

target 1 12 1 ≤6 ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0

title 1 12 1 Yes Yes ≤4 Yes Yes 4 Yes ≤3.2 Yes

`type` 1 12 1 ≤6 ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0 #

:::

<link>: The External Resource Link element #

Try it #

HTML Demo: <link> #

Output #

Console Output #

Attributes #

Non-standard attributes #

Obsolete attributes #

Examples #

Including a stylesheet #

Providing alternative stylesheets #

Providing icons for different usage contexts #

Conditionally loading resources with media queries #

Stylesheet load events #

Preload examples #

Blocking rendering till a resource is fetched #

Technical summary #

Specifications #

::: _table #

Specification #

Browser compatibility #

::: _table #

type 1 12 1 ≤6 ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0 #

See also #

`type` 1 12 1 ≤6 ≤12.1 ≤4 4.4 18 4 ≤12.1 ≤3.2 1.0 #