HTML: The Living Standard

Edition for Web Developers — Last Updated 21 November 2024

1. 1. 2.4 URLs
      1. 2.4.1 Terminology
      2. 2.4.2 CORS settings attributes
      3. 2.4.3 Referrer policy attributes
      4. 2.4.4 Nonce attributes
      5. 2.4.5 Lazy loading attributes
      6. 2.4.6 Blocking attributes
      7. 2.4.7 Fetch priority attributes

2.4 URLs

2.4.1 Terminology

A string is a valid non-empty URL if it is a valid URL string but it is not the empty string.

A string is a valid URL potentially surrounded by spaces if, after stripping leading and trailing ASCII whitespace from it, it is a valid URL string.

A string is a valid non-empty URL potentially surrounded by spaces if, after stripping leading and trailing ASCII whitespace from it, it is a valid non-empty URL.

This specification defines the URL about:legacy-compat as a reserved, though unresolvable, about: URL, for use in DOCTYPEs in HTML documents when needed for compatibility with XML tools. [ABOUT]

This specification defines the URL about:html-kind as a reserved, though unresolvable, about: URL, that is used as an identifier for kinds of media tracks. [ABOUT]

This specification defines the URL about:srcdoc as a reserved, though unresolvable, about: URL, that is used as the URL of iframe srcdoc documents. [ABOUT]

The fallback base URL of a Document object document is the URL record obtained by running these steps:

1. If document is an iframe srcdoc document, then:

   1. Assert: document's about base URL is non-null.

   2. Return document's about base URL.

2. If document's URL matches about:blank and document's about base URL is non-null, then return document's about base URL.

3. Return document's URL.

The document base URL of a Document object is the URL record obtained by running these steps:

1. If there is no base element that has an href attribute in the Document, then return the Document's fallback base URL.

2. Otherwise, return the frozen base URL of the first base element in the Document that has an href attribute, in tree order.

A URL matches about:blank if its scheme is "about", its path contains a single string "blank", its username and password are the empty string, and its host is null.

Such a URL's query and fragment can be non-null. For example, the URL record created by parsing "about:blank?foo#bar" matches about:blank.

A URL matches about:srcdoc if its scheme is "about", its path contains a single string "srcdoc", its query is null, its username and password are the empty string, and its host is null.

The reason that matches about:srcdoc ensures that the URL's query is null is because it is not possible to create an iframe srcdoc document whose URL has a non-null query, unlike Documents whose URL matches about:blank. In other words, the set of all URLs that match about:srcdoc only vary in their fragment.

2.4.2 CORS settings attributes

A CORS settings attribute is an enumerated attribute with the following keywords and states:

The attribute's missing value default is the No CORS state, and its invalid value default is the Anonymous state. For the purposes of reflection, the canonical keyword for the Anonymous state is the anonymous keyword.

The majority of fetches governed by CORS settings attributes will be done via the create a potential-CORS request algorithm.

For more modern features, where the request's mode is always "cors", certain CORS settings attributes have been repurposed to have a slightly different meaning, wherein they only impact the request's credentials mode. To perform this translation, we define the CORS settings attribute credentials mode for a given CORS settings attribute to be determined by switching on the attribute's state:

No CORS

Anonymous

"same-origin"

Use Credentials

"include"

2.4.3 Referrer policy attributes

A referrer policy attribute is an enumerated attribute. Each referrer policy, including the empty string, is a keyword for this attribute, mapping to a state of the same name.

The attribute's missing value default and invalid value default are both the empty string state.

The impact of these states on the processing model of various fetches is defined in more detail throughout this specification, in Fetch, and in Referrer Policy. [FETCH] [REFERRERPOLICY]

2.4.4 Nonce attributes

A nonce content attribute represents a cryptographic nonce ("number used once") which can be used by Content Security Policy to determine whether or not a given fetch will be allowed to proceed. The value is text. [CSP]

Elements that have a nonce content attribute ensure that the cryptographic nonce is only exposed to script (and not to side-channels like CSS attribute selectors) by taking the value from the content attribute, moving it into an internal slot named [[CryptographicNonce]], exposing it to script via the HTMLOrSVGElement interface mixin, and setting the content attribute to the empty string. Unless otherwise specified, the slot's value is the empty string.

element.nonce

Returns the value set for element's cryptographic nonce. If the setter was not used, this will be the value originally found in the nonce content attribute.

element.nonce = value

Updates element's cryptographic nonce value.

The nonce IDL attribute must, on getting, return the value of this element's [[CryptographicNonce]]; and on setting, set this element's [[CryptographicNonce]] to the given value.

Note how the setter for the nonce IDL attribute does not update the corresponding content attribute. This, as well as the below setting of the nonce content attribute to the empty string when an element becomes browsing-context connected, is meant to prevent exfiltration of the nonce value through mechanisms that can easily read content attributes, such as selectors. Learn more in issue #2369, where this behavior was introduced.

The following attribute change steps are used for the nonce content attribute:

1. If element does not include HTMLOrSVGElement, then return.

2. If localName is not nonce or namespace is not null, then return.

3. If value is null, then set element's [[CryptographicNonce]] to the empty string.

4. Otherwise, set element's [[CryptographicNonce]] to value.

Whenever an element including HTMLOrSVGElement becomes browsing-context connected, the user agent must execute the following steps on the element:

1. Let CSP list be element's shadow-including root's policy container's CSP list.

2. If CSP list contains a header-delivered Content Security Policy, and element has a nonce content attribute attr whose value is not the empty string, then:

   1. Let nonce be element's [[CryptographicNonce]].

   2. Set an attribute value for element using "nonce" and the empty string.

   3. Set element's [[CryptographicNonce]] to nonce.

   If element's [[CryptographicNonce]] were not restored it would be the empty string at this point.

The cloning steps for elements that include HTMLOrSVGElement must set the [[CryptographicNonce]] slot on the copy to the value of the slot on the element being cloned.

2.4.5 Lazy loading attributes

A lazy loading attribute is an enumerated attribute with the following keywords and states:

The attribute directs the user agent to fetch a resource immediately or to defer fetching until some conditions associated with the element are met, according to the attribute's current state.

The attribute's missing value default and invalid value default are both the Eager state.

The will lazy load element steps, given an element element, are as follows:

1. If scripting is disabled for element, then return false.

   This is an anti-tracking measure, because if a user agent supported lazy loading when scripting is disabled, it would still be possible for a site to track a user's approximate scroll position throughout a session, by strategically placing images in a page's markup such that a server can track how many images are requested and when.

2. If element's lazy loading attribute is in the Lazy state, then return true.

3. Return false.

Each img and iframe element has associated lazy load resumption steps, initially null.

For img and iframe elements that will lazy load, these steps are run from the lazy load intersection observer's callback or when their lazy loading attribute is set to the Eager state. This causes the element to continue loading.

Each Document has a lazy load intersection observer, initially set to null but can be set to an IntersectionObserver instance.

To start intersection-observing a lazy loading element element, run these steps:

1. Let doc be element's node document.

2. If doc's lazy load intersection observer is null, set it to a new IntersectionObserver instance, initialized as follows:

   The intention is to use the original value of the IntersectionObserver constructor. However, we're forced to use the JavaScript-exposed constructor in this specification, until Intersection Observer exposes low-level hooks for use in specifications. See bug w3c/IntersectionObserver#464 which tracks this. [INTERSECTIONOBSERVER]

   • The callback is these steps, with arguments entries and observer:

     1. For each entry in entries using a method of iteration which does not trigger developer-modifiable array accessors or iteration hooks:

        1. Let resumptionSteps be null.

        2. If entry.isIntersecting is true, then set resumptionSteps to entry.target's lazy load resumption steps.

        3. If resumptionSteps is null, then return.

        4. Stop intersection-observing a lazy loading element for entry.target.

        5. Set entry.target's lazy load resumption steps to null.

        6. Invoke resumptionSteps.

        The intention is to use the original value of the isIntersecting and target getters. See w3c/IntersectionObserver#464. [INTERSECTIONOBSERVER]

   • The options is an IntersectionObserverInit dictionary with the following dictionary members: «[ "scrollMargin" → lazy load scroll margin ]»

     This allows for fetching the image during scrolling, when it does not yet — but is about to — intersect the viewport.

     The lazy load scroll margin suggestions imply dynamic changes to the value, but the IntersectionObserver API does not support changing the scroll margin. See issue w3c/IntersectionObserver#428.

3. Call doc's lazy load intersection observer's observe method with element as the argument.

   The intention is to use the original value of the observe method. See w3c/IntersectionObserver#464. [INTERSECTIONOBSERVER]

To stop intersection-observing a lazy loading element element, run these steps:

1. Let doc be element's node document.

2. Assert: doc's lazy load intersection observer is not null.

3. Call doc's lazy load intersection observer's unobserve method with element as the argument.

   The intention is to use the original value of the unobserve method. See w3c/IntersectionObserver#464. [INTERSECTIONOBSERVER]

The lazy load scroll margin is an implementation-defined value, but with the following suggestions to consider:

• Set a minimum value that most often results in the resources being loaded before they intersect the viewport under normal usage patterns for the given device.

• The typical scrolling speed: increase the value for devices with faster typical scrolling speeds.

• The current scrolling speed or momentum: the UA can attempt to predict where the scrolling will likely stop, and adjust the value accordingly.

• The network quality: increase the value for slow or high-latency connections.

• User preferences can influence the value.

It is important for privacy that the lazy load scroll margin not leak additional information. For example, the typical scrolling speed on the current device could be imprecise so as to not introduce a new fingerprinting vector.

2.4.6 Blocking attributes

A blocking attribute explicitly indicates that certain operations should be blocked on the fetching of an external resource. The operations that can be blocked are represented by possible blocking tokens, which are strings listed by the following table:

In the future, there might be more possible blocking tokens.

A blocking attribute must have a value that is an unordered set of unique space-separated tokens, each of which are possible blocking tokens. The supported tokens of a blocking attribute are the possible blocking tokens. Any element can have at most one blocking attribute.

The blocking tokens set for an element el are the result of the following steps:

1. Let value be the value of el's blocking attribute, or the empty string if no such attribute exists.

2. Set value to value, converted to ASCII lowercase.

3. Let rawTokens be the result of splitting value on ASCII whitespace.

4. Return a set containing the elements of rawTokens that are possible blocking tokens.

An element is potentially render-blocking if its blocking tokens set contains "render", or if it is implicitly potentially render-blocking, which will be defined at the individual elements. By default, an element is not implicitly potentially render-blocking.

2.4.7 Fetch priority attributes

A fetch priority attribute is an enumerated attribute with the following keywords and states:

The attribute's missing value default and invalid value default are both the auto state.