HTML blocking Attribute

HTML blocking Attribute

The HTML blocking attribute indicates that certain operations should be blocked while an element or its resource is being processed. Its currently defined value is render, which makes an eligible <link>, <script>, or <style> element potentially render-blocking.

Syntax

The blocking attribute contains one or more space-separated blocking tokens. At present, the only defined blocking token is render.

<script src="script.js" blocking="render"></script>

The render token indicates that the element is potentially render-blocking.

Attribute Values

The blocking attribute is defined as an unordered set of unique space-separated tokens. HTML currently defines one blocking token.

Additional blocking tokens may be defined in the future, so the attribute is designed to support more than one space-separated token.

Elements That Use the blocking Attribute

The blocking attribute is currently valid on the <link>, <script>, and <style> elements, subject to the rules that apply to each element.

Using the blocking Attribute

Setting blocking="render" explicitly marks an eligible element as potentially render-blocking. This can be useful when a resource or style must be processed before the browser continues with rendering.

<script src="important.js" blocking="render"></script>

The attribute controls render-blocking behavior; it does not simply mean that all browser activity stops while the resource is being processed.

Using blocking with <link>

On the <link> element, the blocking attribute is used with supported link relationships. The HTML Standard currently allows it with stylesheet and expect.

<link rel="stylesheet" href="styles.css" blocking="render">

A stylesheet discovered by the parser can already be render-blocking under normal processing rules. The blocking attribute provides an explicit way to indicate potential render blocking where the applicable link processing rules allow it.

Using blocking with <script>

The blocking attribute can be specified on eligible external classic and external module scripts.

<script src="script.js" blocking="render"></script>

For a script to participate in render blocking, it must also satisfy the browser's render-blocking processing rules. Adding the attribute does not make every script render-blocking in every situation.

Using blocking with <style>

The blocking attribute can also be specified on a <style> element.

<style blocking="render">
  body {
    font-family: Arial, Helvetica, sans-serif;
  }
</style>

A parser-created <style> element is already implicitly potentially render-blocking. The attribute can explicitly indicate render-blocking behavior where applicable.

Render-Blocking Behavior

Render blocking delays rendering while the browser waits for an eligible element or resource to reach the point where rendering can continue. This can be useful when displaying the page before a critical resource is ready would produce an incomplete or incorrect initial presentation.

Render blocking should be used carefully because delaying rendering can also delay when users first see page content. Use it only when the resource or operation genuinely needs to be completed before rendering proceeds.

Common Mistakes

Do not treat blocking as a Boolean attribute. It requires a token value such as render.

<!-- Correct -->
<script src="script.js" blocking="render"></script>

Do not assume that blocking="render" stops HTML parsing or every other browser operation. It specifically participates in the document's render-blocking mechanism.

Do not add blocking="render" to resources unnecessarily. Excessive render blocking can delay the initial display of a page.

Browser Support

Baseline: Limited availability indicates that a feature is not yet available in all core browsers. Use these features with caution because they may only work in select browsers, so additional compatibility checks may be needed before general use.

The blocking attribute has limited availability. Support can vary by element and by the render blocking token, so test its use in the browsers required by your project.

Checking Browser Support

For current browser compatibility information, visit Can I Use? . Search for the HTML element or attribute you want to check. You can also narrow your search by entering an element name and attribute name separated by a colon. Search results can include related HTML features, element attributes, input types, APIs, and other technologies, so select the result that most closely matches the feature you are checking.

Try the blocking Attribute

The example uses blocking="render" on a <style> element. The visible result is ordinary CSS styling because render blocking affects when the browser may render the document rather than creating a separate visual effect.

Summary

The HTML blocking attribute identifies operations that should block while an eligible element or resource is being processed. It is currently supported on the <link>, <script>, and <style> elements, and the only currently defined blocking token is render. Because render blocking can delay the initial display of a page, use the attribute only when the resource needs to participate in render-blocking behavior.