HTMLImageElement.fetchPriority - improve

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

@@ -8,33 +8,34 @@ browser-compat: api.HTMLImageElement.fetchPriority
 
 {{APIRef}}
 
-The **`fetchPriority`** property of the
-{{domxref("HTMLImageElement")}} interface represents a hint given to the browser on how
-it should prioritize the fetch of the image relative to other images.
+The **`fetchPriority`** property of the {{domxref("HTMLImageElement")}} interface represents a hint to the browser indicating how it should prioritize fetching the image relative to other images with the same default priority.
+It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Element/img#fetchpriority) attribute of the corresponding {{htmlelement("img")}} element, for the allowed values.
+
+Generally speaking browsers use a sensible default prioritization for fetching images, based on factors such as whether they will be in the visual viewport on page load, or in some other context where they are more or less likely to become visible to the user.
+The property allows a developer to signal to the browser that a particular image has more or less impact on user experience than would be expected given its default prioritization.
+This in turn allows the browser to increase or decrease the priority, and potentially load the image earlier or later than it would otherwise.
+
+Note that the hint, if accepted, incrementally increases or decreases the image fetching priority up or down from its default prioritization.
+For example, an offscreen image might have a default priority of "low", and this hint could raise the priority to "medium" or lower it to "very low".
+However it can't increase the priority to be "high" like an image in the visual viewport, or to be above the maximum or below the minimum priority levels.
+Note also that the default priorities are browser specific, and so the effects of the hint may vary across browser engines.
+
+The property should be used sparingly, as excessive and incorrect prioritization can degrade performance.
 
 ## Value
 
-A string representing the priority hint. Possible values are:
+A string representing the priority hint.
+Possible values are:
 
 - `high`
-  - : Fetch the image at a high priority relative to other images.
+  - : Fetch the image at a high priority relative to other images with the same default prioritization.
 - `low`
-  - : Fetch the image at a low priority relative to other images.
+  - : Fetch the image at a low priority relative to other images with the same default 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 image
-fetches. This can be useful when applied to {{HTMLElement("img")}} elements
-to signal images that are "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 image automatically. Over use can result in
-degrading performance.
+The property is `null` or an empty string if any other value is set.
 
 ## Examples
 
@@ -56,3 +57,5 @@ img.src = "img/logo.png";
 
 - {{domxref("HTMLLinkElement.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) on web.dev