React Reference ยท Built-in DOM Components
The React link element
Reference for the React link element: hoist canonical and icon links to the head, load stylesheets with precedence, and understand deduplication and Suspense.
<link> connects the document to an external resource: a stylesheet, an icon, a canonical URL, an alternate language version, a preload hint. React 19 lets any component render a <link>, and for the cases that belong in the <head> it moves the element there for you.
There are two behaviors. A stylesheet link with a precedence prop is a managed resource: React places it in the head in a group, removes duplicates when several components ask for the same href, and holds back the content that needs it (using Suspense) until the file has loaded, so users do not see unstyled content. Other links (canonical, icon, alternate, preload, and so on) are simply hoisted to the head.
function Widget() { return ( <> <link rel="stylesheet" href="/css/widget.css" precedence="default" /> <div className="widget">...</div> </> ); }
Try it
Syntax
<link rel="stylesheet" href="/a.css" precedence="default" /> <link rel="canonical" href="https://example.com/page" /> <link rel="preload" href="/font.woff2" as="font" crossOrigin="anonymous" />
| Name | Description |
|---|---|
rel |
The relationship: stylesheet, icon, canonical, alternate, preload, preconnect, modulepreload, and so on. |
href |
The URL of the resource. Required for hoisting. |
precedence |
A string. Makes a stylesheet managed: grouped, deduplicated and awaited. Groups are ordered by first use. |
as, type, media, sizes, hrefLang, integrity, crossOrigin, referrerPolicy, fetchPriority |
Same meaning as in HTML (camelCase in JSX). |
onLoad, onError |
Called when the resource loads or fails. Using them stops React from hoisting the link. |
disabled |
A stylesheet with a disabled prop is not managed by React either. |
Returns: an HTMLLinkElement in document.head.
Edge cases: a stylesheet without precedence is not hoisted and behaves like a normal element in the component's position. A link without rel and href strings is rendered where it stands.
Usage notes
- Precedence orders the CSS. Stylesheets with the same
precedencevalue sit together; a new precedence name is placed after the groups already known. Use names likereset,base,componentsin the order you want the cascade. - Deduplication is by
href. Ten components that render the same stylesheet add one link to the head. Do not depend on the order of components within one precedence. - Suspense. A component that renders a managed stylesheet suspends until the file has loaded, so wrap such parts in
<Suspense>to control the fallback. Without one, the whole tree below the root waits. - Removal. React keeps a managed stylesheet in the head even after the component unmounts (the rules may still be needed by other pages).
- Preload helpers. The
preload,preinit,preconnectandprefetchDNSfunctions fromreact-domstart resource loading from code, without rendering a<link>. - Static shells. Fonts, the main CSS bundle and the favicon usually belong in the HTML template. Component-level
<link>shines for CSS tied to optional or lazily rendered parts. - Server rendering. Managed stylesheets are emitted into the head and sent before the content that needs them, which avoids a flash of unstyled content.
- Canonical links. Render one canonical link per page, and give it the full absolute URL.