HTMLLinkElement.fetchPriority

files/en-us/web/api/htmllinkelement/fetchpriority/index.md

@@ -8,37 +8,29 @@ browser-compat: api.HTMLLinkElement.fetchPriority
 
 {{APIRef("HTML DOM")}}
 
-The **`fetchPriority`** property of the
-{{domxref("HTMLLinkElement")}} interface represents a hint given to the browser
-on how it should prioritize the preload of the given resource relative to other
-resources of the same
-[type](/en-US/docs/Web/HTML/Attributes/rel/preload#what_types_of_content_can_be_preloaded).
+The **`fetchPriority`** property of the {{domxref("HTMLLinkElement")}} interface represents a hint to the browser indicating how it should prioritize fetching a given resource relative to other
+resources of the same type and internal prioritization.
+It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Element/link#fetchpriority) attribute of the corresponding {{htmlelement("link")}} element, for the allowed values.
+
+The property allows a developer to signal that fetching a particular resource early in the loading process has more or less impact on user experience than a browser can reasonably infer when assigning an internal priority, in particular when preloading resources.
+This in turn allows the browser to increase or decrease the priority, and potentially load the resource earlier or later than it would otherwise.
+The property should be used sparingly, as excessive or incorrect prioritization can degrade performance.
+
+Note that both the internal priority of any fetch operation, and the impact of `fetchPriority` on the priority, are entirely browser dependent.
 
 ## Value
 
 A string representing the priority hint. Possible values are:
 
 - `high`
-  - : Fetch the preload resource at a high priority relative to other resources
-    of the same type.
+  - : Fetch the preload resource at a high priority relative to other resources of the same type and internal prioritization.
 - `low`
-  - : Fetch the preload resource at a low priority relative to other resources of
-    the same type.
+  - : Fetch the preload resource at a low priority relative to other resources of the same type and internal prioritization.
 - `auto`
-  - : Default mode, which indicates no preference for
-    the fetch priority. The browser decides what is best for the user.
-
-The `fetchPriority` property allows you to signal high or low priority preload
-fetches. This can be useful when applied to {{HTMLElement("link")}} elements
-to signal preloads that are more or less important to the user experience early
-in the loading process.
-
-The effects of the hint on resource loading is browser-specific so make sure to
-test on multiple browser engines.
+  - : No user preference for the fetch priority.
+    This is the default.
 
-Use it sparingly for exceptional cases where the browser may not be able to
-infer the best way to load the resource automatically. Over use can result in
-degrading performance.
+The property is `null` or an empty string if any other value is set.
 
 ## Examples
 
@@ -63,3 +55,5 @@ document.head.appendChild(preloadLink);
 
 - {{domxref("HTMLImageElement.fetchPriority")}}
 - {{domxref("HTMLScriptElement.fetchPriority")}}
+- HTTP {{httpheader("Link")}} header
+- [Optimize resource loading with the Fetch Priority API](https://web.dev/articles/fetch-priority?hl=en#browser_priority_and_fetchpriority) for information about how this API affects priorities on Chrome.