React Reference ยท react-dom Resource and Form APIs
Stylesheet precedence in React
Reference for the precedence prop on link rel=stylesheet in React 19: how groups set the cascade order, how duplicates are merged, and when React waits for CSS.
When a component renders <link rel="stylesheet" href="..." precedence="...">, React takes over that stylesheet. It moves the <link> into the head, loads each distinct href only once however many components ask for it, and places it in the right position among the other stylesheets. The precedence prop is what makes ordering possible: stylesheets with the same precedence form a group, and groups are kept in the order in which each precedence name was first seen.
This solves an old problem of component-based CSS: a component can ask for the exact stylesheet it needs, and the page still ends up with predictable cascade order, no duplicates, and, with server rendering, the right stylesheets in the right place even for content that streams in later.
function Card() { return ( <> <link rel="stylesheet" href="/css/card.css" precedence="default" /> <div className="card">...</div> </> ); }
Try it
DeepWidget rendered its sheet last, but because its precedence base was already known, React inserted it into the base group, before the theme sheet. The paragraph is therefore green (the theme rule is later in the cascade) and bold.
Syntax
<link rel="stylesheet" href="..." precedence="..." />
interface StylesheetLinkProps { rel: 'stylesheet'; href: string; precedence: string; media?: string; crossOrigin?: string; integrity?: string; }
| Prop | Description |
|---|---|
href |
Identity of the stylesheet. Two links with the same href are the same resource. Required. |
precedence |
A name you choose, such as "reset", "base", "theme", "default". Enables the behavior on this page; without it the <link> is an ordinary element that stays where you wrote it. |
media, crossOrigin, integrity, nonce |
Passed to the real <link>. |
disabled, onLoad, onError |
Do not combine these with precedence. React then treats the link as a plain element, does not hoist or deduplicate it, and logs a development warning. |
Returns: these are JSX elements, nothing is returned. preinit with as: 'style' creates the same managed resource from code.
Errors / edge cases: if two links with the same href have different props (say another media or precedence), the first one rendered wins and the second is ignored without an error.
Usage notes
- Groups are ordered by first appearance, not alphabetically. The first precedence name React meets gets the earliest slot, the next new name the next slot, and so on. Declare the broadest layer first (reset, base) in your layout or root component to make the order obvious.
- Within a group, order follows render order. A late sheet with a known precedence is inserted at the end of its own group, so it can still land earlier than a sheet from a later group, as in the first example.
- Later in the cascade wins at equal specificity, exactly as with normal stylesheets. Precedence decides cascade position, not importance.
- React may wait for the CSS. On the client, React can hold back showing new content until its stylesheets have loaded (it suspends), to avoid a flash of unstyled content. Wrap such content in
<Suspense>if you want a fallback. In streamed server rendering, the stylesheets are sent with the content that needs them. - Stylesheets are not removed. Once added, a
precedencestylesheet stays in the head even after the component that requested it unmounts. - Use stable
hrefvalues. Hashed filenames from your bundler are ideal; a changing query string creates a new resource each time. - Prefer a small number of group names, typically two or three.
- A plain
<link>withoutprecedencedoes not take part in any of this and is not deduplicated.