Image Resource

W3C Working Draft

This version:
Latest published version:
Latest editor's draft:
Previous version:
Aaron Gustafson (Microsoft Corporation)
Rayan Kanso (Google Inc.)
Marcos Cáceres (W3C Invited Expert)
GitHub w3c/image-resource
File a bug
Commit history
Pull requests


This document defines the concept of an "image resource" and a corresponding WebIDL ImageResource dictionary. Web APIs can use the ImageResource dictionary to represent an image resource in contexts where an HTMLImageElement is not suitable or available (e.g., in a Worker).

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at


This specification is not stable. Implementors who are not taking part in the discussions will find the specification changing out from under them in incompatible ways.

This document was published by the Web Applications Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

GitHub Issues are preferred for discussion of this specification.

Publication as a Working Draft does not imply endorsement by the W3C Membership.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 15 September 2020 W3C Process Document.

1. Introduction

Web applications often accept developer-provided image resources to be displayed outside of a HTML document (e.g., in the OS, in the browser UI, etc.). This specification defines a WebIDL dictionary that describes an image, and where that image resource can be fetched from. The user agent can then use this extra information to choose an image that is best suited to display on the end-user's device or most closely matches the end-user's preferences or environment.

2. Privacy and security considerations

Fetching an image resource can reveal the user's IP address. It is RECOMMENDED that user agents fetch the chosen image resources when provided by the developer, and store them for re-use if needed. This limits tracking the user's location over time.

3. Image resource

An image resource consists of:

A URL from where to obtain the image data.
An optional string representing the sizes of the image, expressed using the same syntax as link's sizes attribute.
An optional image MIME type.
A string representing the accessible name of the image.

In an API, an image resource is represented as an ImageResource dictionary.

In [JSON], image resource is represented as an object.

4. ImageResource dictionary

WebIDLdictionary ImageResource {
  required USVString src;
  DOMString sizes;
  DOMString type;
  DOMString label;

4.1 src member

The src of an ImageResource is a URL from which a user agent can fetch image data.

4.2 sizes member

The sizes member is equivalent to a link element's sizes attribute, and is processed in the same manner.

When multiple ImageResource dictionaries are available, a user agent MAY use the sizes value to decide which image is most suitable for a display context (and ignore any that are inappropriate).

The sizes member allows for multiple space-separated size values in order to accommodate image formats (such as ICO) that can act as a container for multiple images of varying dimensions.
const image = {
  src: "path/to/image.ico",
  sizes: "16x16 32x32 64x64",
  type: "image/",

4.3 type member

The type member represents an image MIME Type for the image resource. A user agent MAY ignore media types it does not support.

There is no default MIME type for an ImageResource. The type is purely advisory. User agents MUST use the rules for sniffing images specifically to determine the computed MIME type of an image resource.

4.4 label member

The label of an ImageResource is a string that provides the accessible name for the associated image.

Implementors MUST derive the accessible name for every ImageResource they expose to users.

Authors are strongly encouraged to add a label unless the ImageResource’s accessible name can be inferred from an external label in its context. For example, in the context of a manifest, the name (or short_name) provides an external label for all members of the icons array that don’t have a label defined.

If neither an explicit label nor an external label is provided, but the type supports providing an embedded accessible name, implementors MAY choose to defer assigning the label until the src has been fetched and processed. If the src is found to provide an embedded accessible name, implementors MUST update the label to match that value.

5. Processing an ImageResource from an API

The steps to process an ImageResource from an API are given by the following algorithm. The algorithm takes an ImageResource input. It returns an image resource.

  1. Let base URL be the relevant settings object’s api base url from where this dictionary is being used.
  2. Let image be a new image resource.
  3. Set image's src to the result of URL parsing input.src and base URL. If parsing the URL fails, throw a TypeError.
  4. If input's sizes member is present:
    1. Set image's sizes to the result of parsing input.sizes as if it was a sizes attribute of a link element whose rel attribute contains the token icon. If parsing fails, throw a TypeError.
  5. If input's type member is present and not the empty string:
    1. If type is not an image MIME Type, throw a TypeError.
    2. Set image's type to input.type.
  6. Set image's label to the result of deriving the accessible name.
  7. Return image.

6. Processing an image resource from JSON

To process an image resource from JSON, given a JSON Object input and a URL base. It returns an ordered map.

  1. If input is not of type object, return failure.
  2. If input["src"] is not of type string, return failure.
  3. Let src be the result of parsing input["src"] with base as the base URL.
  4. If src is failure, return failure.
  5. Let image be an new ordered map.
  6. Set image["src"] to src.
  7. If type of input["sizes"] is a string, and its length is greater than zero:
    1. Set sizes to the result of parsing input["sizes"] as if it was a sizes attribute of a link element whose rel attribute contains the token icon.
    2. If sizes is failure, return failure.
    3. Set image["sizes"] to sizes.
  8. If input["type"] is a string, and it has a length greater than zero:
    1. Let mime be the result of parsing input["type"].
    2. If mime is failure, return failure.
    3. Set image["type"] to the essence of mime.
  9. Set image["label"] to the result of deriving the accessible name.
  10. Return image.

7. Fetching an image resource

The steps for fetching an image resource are given by the following algorithm. The algorithm takes an image resource image, and an optional Request request. It returns a Response.

  1. If request is undefined:
    1. Set request to a new Request.
    2. Set URL to image's src.
    3. Set Destination to "image".
    4. Set Client to the context object's relevant settings object.
  2. If request's Client is null, throw a TypeError.
  3. Perform a fetch using request and return the Response.

8. Deriving the accessible name

The steps to derive the accessible name for an image resource resource are as follows. It returns a string.

  1. If resource["label"] is a string, return input["label"].
  2. Otherwise, if image provides an embedded accessible name, return the embedded accessible name.
  3. Otherwise, if an external label can be substituted, return the relevant external label.
  4. Return "".

9. Examples of graphics formats supporting embedded accessible names

Certain graphics formats support the inclusion of an embedded accessible name as part of the image’s contents. Examples include:

10. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and RECOMMENDED in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A. References

A.1 Normative references

Web Application Manifest. Marcos Caceres; Kenneth Christiansen; Mounir Lamouri; Anssi Kostiainen; Matt Giuca; Aaron Gustafson. W3C. 9 March 2021. W3C Working Draft. URL:
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL:
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL:
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL:
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL:
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL:
MIME Sniffing Standard. Gordon P. Hemsley. WHATWG. Living Standard. URL:
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL:
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL:
Scalable Vector Graphics (SVG) 1.0 Specification. Jon Ferraiolo. W3C. 4 September 2001. W3C Recommendation. URL:
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL:
Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: