20/02/2025, 18:27 <link> – React
v19
API REFERENCE COMPONENTS
<link>
The built-in browser <link> component lets you use external
resources such as stylesheets or annotate the document with link
metadata.
<link rel="icon" href="favicon.ico" />
Reference
<link>
Usage
Linking to related resources
Linking to a stylesheet
Controlling stylesheet precedence
Deduplicated stylesheet rendering
Annotating specific items within the document with links
Reference
<link>
To link to external resources such as stylesheets, fonts, and icons, or to
annotate the document with link metadata, render the built-in browser
<link> component. You can render <link> from any component and React
will in most cases place the corresponding DOM element in the document
head.
https://react.dev/reference/react-dom/components/link 1/10
20/02/2025, 18:27 <link> – React
<link rel="icon" href="favicon.ico" />
See more examples below.
Props
<link> supports all common element props.
rel : a string, required. Specifies the relationship to the resource. React
treats links with rel="stylesheet" differently from other links.
These props apply when rel="stylesheet" :
precedence : a string. Tells React where to rank the <link> DOM node
relative to others in the document <head> , which determines which
stylesheet can override the other. React will infer that precedence values
it discovers first are “lower” and precedence values it discovers later are
“higher”. Many style systems can work fine using a single precedence
value because style rules are atomic. Stylesheets with the same
precedence go together whether they are <link> or inline <style> tags
or loaded using preinit functions.
media : a string. Restricts the stylesheet to a certain media query.
title : a string. Specifies the name of an alternative stylesheet.
These props apply when rel="stylesheet" but disable React’s special
treatment of stylesheets:
disabled : a boolean. Disables the stylesheet.
onError : a function. Called when the stylesheet fails to load.
onLoad : a function. Called when the stylesheet finishes being loaded.
These props apply when rel="preload" or rel="modulepreload" :
as : a string. The type of resource. Its possible values are audio ,
document , embed , fetch , font , image , object , script , style , track ,
video , worker .
imageSrcSet : a string. Applicable only when as="image" . Specifies the
source set of the image.
https://react.dev/reference/react-dom/components/link 2/10
20/02/2025, 18:27 <link> – React
imageSizes : a string. Applicable only when as="image" . Specifies the
sizes of the image.
These props apply when rel="icon" or rel="apple-touch-icon" :
sizes : a string. The sizes of the icon.
These props apply in all cases:
href : a string. The URL of the linked resource.
crossOrigin : a string. The CORS policy to use. Its possible values are
anonymous and use-credentials . It is required when as is set to
"fetch" .
referrerPolicy : a string. The Referrer header to send when fetching. Its
possible values are no-referrer-when-downgrade (the default), no-
referrer , origin , origin-when-cross-origin , and unsafe-url .
fetchPriority : a string. Suggests a relative priority for fetching the
resource. The possible values are auto (the default), high , and low .
hrefLang : a string. The language of the linked resource.
integrity : a string. A cryptographic hash of the resource, to verify its
authenticity.
type : a string. The MIME type of the linked resource.
Props that are not recommended for use with React:
blocking : a string. If set to "render" , instructs the browser not to render
the page until the stylesheet is loaded. React provides more fine-grained
control using Suspense.
Special rendering behavior
React will always place the DOM element corresponding to the <link>
component within the document’s <head> , regardless of where in the React
tree it is rendered. The <head> is the only valid place for <link> to exist
within the DOM, yet it’s convenient and keeps things composable if a
component representing a specific page can render <link> components
itself.
There are a few exceptions to this:
https://react.dev/reference/react-dom/components/link 3/10
20/02/2025, 18:27 <link> – React
If the <link> has a rel="stylesheet" prop, then it has to also have a
precedence prop to get this special behavior. This is because the order of
stylesheets within the document is significant, so React needs to know
how to order this stylesheet relative to others, which you specify using
the precedence prop. If the precedence prop is omitted, there is no
special behavior.
If the <link> has an itemProp prop, there is no special behavior, because
in this case it doesn’t apply to the document but instead represents
metadata about a specific part of the page.
If the <link> has an onLoad or onError prop, because in that case you
are managing the loading of the linked resource manually within your
React component.
Special behavior for stylesheets
In addition, if the <link> is to a stylesheet (namely, it has rel="stylesheet"
in its props), React treats it specially in the following ways:
The component that renders <link> will suspend while the stylesheet is
loading.
If multiple components render links to the same stylesheet, React will de-
duplicate them and only put a single link into the DOM. Two links are
considered the same if they have the same href prop.
There are two exception to this special behavior:
If the link doesn’t have a precedence prop, there is no special behavior,
because the order of stylesheets within the document is significant, so
React needs to know how to order this stylesheet relative to others, which
you specify using the precedence prop.
If you supply any of the onLoad , onError , or disabled props, there is no
special behavior, because these props indicate that you are managing the
loading of the stylesheet manually within your component.
This special treatment comes with two caveats:
React will ignore changes to props after the link has been rendered.
(React will issue a warning in development if this happens.)
https://react.dev/reference/react-dom/components/link 4/10
20/02/2025, 18:27 <link> – React
React may leave the link in the DOM even after the component that
rendered it has been unmounted.
Usage
Linking to related resources
You can annotate the document with links to related resources such as an
icon, canonical URL, or pingback. React will place this metadata within the
document <head> regardless of where in the React tree it is rendered.
App.js ShowRenderedHTML.js Reset
import ShowRenderedHTML from './ShowRenderedHTML.js';
export default function BlogPage() {
return (
<ShowRenderedHTML>
<link rel="icon" href="favicon.ico" />
<link rel="pingback" href="http://www.example.com/xmlrpc.php" /
<h1>My Blog</h1>
<p>...</p>
</ShowRenderedHTML>
);
https://react.dev/reference/react-dom/components/link 5/10
20/02/2025, 18:27 <link> – React
Linking to a stylesheet
If a component depends on a certain stylesheet in order to be displayed
correctly, you can render a link to that stylesheet within the component. Your
component will suspend while the stylesheet is loading. You must supply the
precedence prop, which tells React where to place this stylesheet relative to
others — stylesheets with higher precedence can override those with lower
precedence.
Note
When you want to use a stylesheet, it can be beneficial to call the
preinit function. Calling this function may allow the browser to start
fetching the stylesheet earlier than if you just render a <link>
component, for example by sending an HTTP Early Hints response.
App.js ShowRenderedHTML.js Reset
import ShowRenderedHTML from './ShowRenderedHTML.js';
export default function SiteMapPage() {
return (
<ShowRenderedHTML>
<link rel="stylesheet" href="sitemap.css" precedence="medium" />
<p>...</p>
</ShowRenderedHTML>
);
}
https://react.dev/reference/react-dom/components/link 6/10
20/02/2025, 18:27 <link> – React
Controlling stylesheet precedence
Stylesheets can conflict with each other, and when they do, the browser goes
with the one that comes later in the document. React lets you control the
order of stylesheets with the precedence prop. In this example, three
components render stylesheets, and the ones with the same precedence are
grouped together in the <head> .
App.js ShowRenderedHTML.js Reset
import ShowRenderedHTML from './ShowRenderedHTML.js';
export default function HomePage() {
return (
<ShowRenderedHTML>
<FirstComponent />
<SecondComponent />
<ThirdComponent/>
...
</ShowRenderedHTML>
);
Show more
https://react.dev/reference/react-dom/components/link 7/10
20/02/2025, 18:27 <link> – React
Note the precedence values themselves are arbitrary and their naming is up
to you. React will infer that precedence values it discovers first are “lower”
and precedence values it discovers later are “higher”.
Deduplicated stylesheet rendering
If you render the same stylesheet from multiple components, React will
place only a single <link> in the document head.
App.js ShowRenderedHTML.js Reset
import ShowRenderedHTML from './ShowRenderedHTML.js';
export default function HomePage() {
return (
<ShowRenderedHTML>
<Component />
<Component />
...
</ShowRenderedHTML>
);
}
https://react.dev/reference/react-dom/components/link 8/10
20/02/2025, 18:27 <link> – React
Annotating specific items within the document with
links
You can use the <link> component with the itemProp prop to annotate
specific items within the document with links to related resources. In this
case, React will not place these annotations within the document <head>
but will place them like any other React component.
<section itemScope>
<h3>Annotating specific items</h3>
<link itemProp="author" href="http://example.com/" />
<p>...</p>
</section>
PREVIOUS
<textarea>
https://react.dev/reference/react-dom/components/link 9/10
20/02/2025, 18:27 <link> – React
NEXT
<meta>
Copyright © Meta Platforms, Inc
uwu?
Learn React API Reference
Quick Start React APIs
Installation React DOM APIs
Describing the UI
Adding Interactivity
Managing State
Escape Hatches
Community More
Code of Conduct Blog
Meet the Team React Native
Docs Contributors Privacy
Acknowledgements Terms
https://react.dev/reference/react-dom/components/link 10/10
