Clarify requirements for render-blocking (mdn#39809)

eeeps · Josh-Cena · github-actions[bot] · web-flow · commit 0e2ec54f4eb5 · 2025-08-13T12:45:05.000-04:00
* Clarify requirements for render-blocking Fixes mdn#39663 Also make clear that we are not only blocking on fetching; also on parsing/application. * Update notes * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update index.md --------- Co-authored-by: Joshua Chen <sidachen2003@gmail.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
diff --git a/files/en-us/web/api/htmllinkelement/blocking/index.md b/files/en-us/web/api/htmllinkelement/blocking/index.md
@@ -19,6 +19,9 @@ A string. Must be a space-separated list of blocking tokens listed below indicat
 - `render`
   - : The rendering of content on the screen is blocked.
 
+    > [!NOTE]
+    > Only `link` elements in the document's `<head>` can possibly block rendering. By default, a `link` element with `rel="stylesheet"` in the `<head>` blocks rendering when the browser discovers it during parsing. If such a `link` element is added dynamically via script, you must additionally set `blocking = "render"` for it to block rendering.
+
 ## Examples
 
 ```html
diff --git a/files/en-us/web/api/htmlscriptelement/blocking/index.md b/files/en-us/web/api/htmlscriptelement/blocking/index.md
@@ -19,6 +19,9 @@ A string. Must be a space-separated list of blocking tokens listed below indicat
 - `render`
   - : The rendering of content on the screen is blocked.
 
+    > [!NOTE]
+    > Only `script` elements in the document's `<head>` can possibly block rendering. Scripts are not render-blocking by default; if a `script` element does not include `type="module"`, `async`, or `defer`, then it blocks _parsing_, not _rendering_. If such a `script` element is added dynamically via script, you must set `blocking = "render"` for it to block rendering.
+
 ## Examples
 
 ```html
diff --git a/files/en-us/web/api/htmlstyleelement/blocking/index.md b/files/en-us/web/api/htmlstyleelement/blocking/index.md
@@ -19,6 +19,9 @@ A string. Must be a space-separated list of blocking tokens listed below indicat
 - `render`
   - : The rendering of content on the screen is blocked.
 
+    > [!NOTE]
+    > Only `style` elements in the document's `<head>` can possibly block rendering. By default, a `style` element in the `<head>` blocks rendering when the browser discovers it during parsing. If such a `style` element is added dynamically via script, you must additionally set `blocking = "render"` for it to block rendering.
+
 ## Examples
 
 ```html
diff --git a/files/en-us/web/api/view_transition_api/using/index.md b/files/en-us/web/api/view_transition_api/using/index.md
@@ -501,14 +501,17 @@ Before running a cross-document transition, you ideally want to wait until the s
 2. Critical scripts are loaded and run.
 3. The HTML visible for the user's initial view of the page has been parsed, so it renders consistently.
 
-Styles are render blocked by default, and scripts can be render blocked using the [`blocking="render"`](/en-US/docs/Web/HTML/Reference/Elements/script#blocking) attribute.
+Styles are render blocked by default unless they are added to the document dynamically, via script. Both scripts and dynamically-added styles can be render blocked using the [`blocking="render"`](/en-US/docs/Web/HTML/Reference/Elements/script#blocking) attribute.
 
 To ensure that your initial HTML has been parsed and will always render consistently before the transition animation runs, you can use [`<link rel="expect">`](/en-US/docs/Web/HTML/Reference/Attributes/rel#expect). In this element, you include the following attributes:
 
 - `rel="expect"` to indicate that you want to use this `<link>` element to render block some HTML on the page.
 - `href="#element-id"` to indicate the ID of the element you want to render block.
 - `blocking="render"` to render block the specified HTML.
 
+> [!NOTE]
+> In order to block rendering, `script`, `link`, and `style` elements with `blocking="render"` must be in the `head` of the document.
+
 Let's explore what this looks like with an example HTML document:
 
 ```html
diff --git a/files/en-us/web/html/reference/attributes/rel/index.md b/files/en-us/web/html/reference/attributes/rel/index.md
@@ -26,7 +26,7 @@ The following table lists some of the most important existing keywords. Every ke
 | [`compression-dictionary`](/en-US/docs/Web/HTML/Reference/Attributes/rel/compression-dictionary) | Link to a {{glossary("Compression dictionary transport", "compression dictionary")}} that can be used to compress future downloads for resources on this site.                                                                                                                                     | Link                    | Not allowed                                      | Not allowed             |
 | [`dns-prefetch`](/en-US/docs/Web/HTML/Reference/Attributes/rel/dns-prefetch)                     | Tells the browser to preemptively perform DNS resolution for the target resource's origin.                                                                                                                                                                                                         | External Resource       | Not allowed                                      | Not allowed             |
 | [`external`](#external)                                                                          | The referenced document is not part of the same site as the current document.                                                                                                                                                                                                                      | Not allowed             | Annotation                                       | Annotation              |
-| [`expect`](#expect)                                                                              | Allows the page to be [render-blocked](/en-US/docs/Glossary/Render_blocking) until the essential parts of the document are parsed so it will render consistently.                                                                                                                                  | Link                    | Not allowed                                      | Not allowed             |
+| [`expect`](#expect)                                                                              | When used with [`blocking="render"`](/en-US/docs/Web/HTML/Reference/Elements/link#blocking), allows the page to be [render-blocked](/en-US/docs/Glossary/Render_blocking) until the essential parts of the document are parsed so it will render consistently.                                     | Link                    | Not allowed                                      | Not allowed             |
 | [`help`](#help)                                                                                  | Link to context-sensitive help.                                                                                                                                                                                                                                                                    | Link                    | Link                                             | Link                    |
 | [`icon`](#icon)                                                                                  | An icon representing the current document.                                                                                                                                                                                                                                                         | External Resource       | Not allowed                                      | Not allowed             |
 | [`license`](#license)                                                                            | Indicates that the main content of the current document is covered by the copyright license described by the referenced document.                                                                                                                                                                  | Link                    | Link                                             | Link                    |
diff --git a/files/en-us/web/html/reference/elements/link/index.md b/files/en-us/web/html/reference/elements/link/index.md
@@ -175,9 +175,12 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Reference/Glo
     </table>
 
 - `blocking`
-  - : This attribute explicitly indicates that certain operations should be blocked on the fetching of an external resource. It must only be used when the `rel` attribute contains `expect` or `stylesheet` keywords. The operations that are to be blocked must be a space-separated list of blocking tokens listed below.
+  - : This attribute explicitly indicates that certain operations should be blocked until specific conditions are met. It must only be used when the `rel` attribute contains the `expect` or `stylesheet` keywords. With [`rel="expect"`](/en-US/docs/Web/HTML/Reference/Attributes/rel#expect), it indicates that operations should be blocked until a specific DOM node has been parsed. With [`rel="stylesheet"`](/en-US/docs/Web/HTML/Reference/Attributes/rel#stylesheet), it indicates that operations should be blocked until an external stylesheet and its critical subresources have been fetched and applied to the document. The operations that are to be blocked must be a space-separated list of blocking tokens listed below. Currently there is only one token:
     - `render`: The rendering of content on the screen is blocked.
 
+    > [!NOTE]
+    > Only `link` elements in the document's `<head>` can possibly block rendering. By default, a `link` element with `rel="stylesheet"` in the `<head>` blocks rendering when the browser discovers it during parsing. If such a `link` element is added dynamically via script, you must additionally set `blocking = "render"` for it to block rendering.
+
 - [`crossorigin`](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin)
   - : This [enumerated](/en-US/docs/Glossary/Enumerated) attribute indicates whether {{Glossary("CORS")}} must be used when fetching the resource.
     [CORS-enabled images](/en-US/docs/Web/HTML/How_to/CORS_enabled_image) can be reused in the {{HTMLElement("canvas")}} element without being _tainted_.
@@ -387,7 +390,7 @@ You can find a number of `<link rel="preload">` examples in [Preloading content
 ### Blocking rendering till a resource is fetched
 
 You can include `render` token inside a `blocking` attribute;
-the rendering of the page will be blocked till the resource is fetched. For example:
+the rendering of the page will be blocked till the resource and its critical subresources are fetched and applied to the document. For example:
 
 ```html
 <link blocking="render" rel="stylesheet" href="example.css" crossorigin />
diff --git a/files/en-us/web/html/reference/elements/script/index.md b/files/en-us/web/html/reference/elements/script/index.md
@@ -52,9 +52,12 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Reference/Glo
     See the [Attribution Reporting API](/en-US/docs/Web/API/Attribution_Reporting_API) for more details.
 
 - `blocking`
-  - : This attribute explicitly indicates that certain operations should be blocked on the fetching of the script. The operations that are to be blocked must be a space-separated list of blocking tokens listed below.
+  - : This attribute explicitly indicates that certain operations should be blocked until the script has executed. The operations that are to be blocked must be a space-separated list of blocking tokens. Currently there is only one token:
     - `render`: The rendering of content on the screen is blocked.
 
+    > [!NOTE]
+    > Only `script` elements in the document's `<head>` can possibly block rendering. Scripts are not render-blocking by default; if a `script` element does not include `type="module"`, `async`, or `defer`, then it blocks _parsing_, not _rendering_. If such a `script` element is added dynamically via script, you must set `blocking = "render"` for it to block rendering.
+
 - [`crossorigin`](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin)
   - : Normal `script` elements pass minimal information to the {{domxref('Window.error_event', 'window.onerror')}} for scripts which do not pass the standard {{Glossary("CORS")}} checks. To allow error logging for sites which use a separate domain for static media, use this attribute. See [CORS settings attributes](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) for a more descriptive explanation of its valid arguments.
 - `defer`
diff --git a/files/en-us/web/html/reference/elements/style/index.md b/files/en-us/web/html/reference/elements/style/index.md
@@ -47,8 +47,12 @@ In the same manner as `<link>` elements, `<style>` elements can include `media`
 This element includes the [global attributes](/en-US/docs/Web/HTML/Reference/Global_attributes).
 
 - `blocking`
-  - : This attribute explicitly indicates that certain operations should be blocked on the fetching of critical subresources. [`@import`](/en-US/docs/Web/CSS/@import)-ed stylesheets are generally considered as critical subresources, whereas [`background-image`](/en-US/docs/Web/CSS/background-image) and fonts are not. The operations that are to be blocked must be a space-separated list of blocking tokens listed below.
+  - : This attribute explicitly indicates that certain operations should be blocked on the fetching of critical subresources and the application of the stylesheet to the document. [`@import`](/en-US/docs/Web/CSS/@import)-ed stylesheets are generally considered as critical subresources, whereas [`background-image`](/en-US/docs/Web/CSS/background-image) and fonts are not. The operations that are to be blocked must be a space-separated list of blocking tokens listed below. Currently there is only one token:
     - `render`: The rendering of content on the screen is blocked.
+
+    > [!NOTE]
+    > Only `style` elements in the document's `<head>` can possibly block rendering. By default, a `style` element in the `<head>` blocks rendering when the browser discovers it during parsing. If such a `style` element is added dynamically via script, you must additionally set `blocking = "render"` for it to block rendering.
+
 - `media`
   - : This attribute defines which media the style should be applied to. Its value is a [media query](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries), which defaults to `all` if the attribute is missing.
 - `nonce`
