Skip to main content

HTML attributes

GitHub repository

Standard <img> attributes​

The web component is a drop-in replacement for the standard <img> tag. It supports all the standard attributes of the <img> tag, such as src=, srcset=, sizes=, width=, etc.

The following standard attributes see their meaning extended.

is= attribute​

The is= attribute is what makes the web component's implementation kick in:

<img
  is="image-display-control"
  src="cats.jpg"
  title="Meow"
  alt="Cats being cute"
  data-image-regions='[{
    "id": "onecatsleeping",
    "names": ["One cat sleeping"],
    "shape": "rectangle",
    "unit": "relative",
    "x": "0.042",
    "y": "0.432",
    "width": "0.248",
    "height": "0.488"
  }, {
    "id": "twocatsplaying",
    "names": ["Two cats playing"],
    "shape": "rectangle",
    "unit": "pixel",
    "imageWidth": "500",
    "imageHeight": "250",
    "x": "170",
    "y": "21",
    "width": "300",
    "height": "114"
  }]'
/>

The is= attribute needs to be present when the <img> element is being added to the DOM. If not present, the browser will create an instance of the standard HTMLImageElement class. Adding the is= attribute later will have no effect.

srcset= and sizes= attributes​

The srcset= and sizes= attributes are supported. They can be used to provide different versions of the image for different screen sizes:

<img
  is="image-display-control"
  src="cats.jpg"
  title="Meow"
  alt="Cats being cute"
  srcset="cats.jpg 2000w, cats-1024x512.jpg 1024w, cats-768x384.jpg 768w"
  sizes="(max-width: 2000px) 100vw, 2000px"
  data-image-regions='[{
    "id": "onecatsleeping",
    "names": ["One cat sleeping"],
    "shape": "rectangle",
    "unit": "relative",
    "x": "0.042",
    "y": "0.432",
    "width": "0.248",
    "height": "0.488"
  }, {
    "id": "twocatsplaying",
    "names": ["Two cats playing"],
    "shape": "rectangle",
    "unit": "pixel",
    "imageWidth": "500",
    "imageHeight": "250",
    "x": "170",
    "y": "21",
    "width": "300",
    "height": "114"
  }]'
/>

Because there are now several source images with different resolutions, defining image regions with coordinates in pixels wouldn't make much sense. We made it possible by specifying a reference imageWidth/imageHeight based on which the regions are defined. See the attribute reference for more details.

Any changes to the srcset= and sizes= attributes will be picked up by the web component.

When zooming in on a region, the web component will make sure to fetch a source image with a large enough resolution. It achieves this by responsively overriding the sizes= attribute.

id= attribute​

The id= attribute is supported and is used, if set, in the prefix for the console output generated by the web component, e.g. when data-log-level=debug:

<img
  id="cats"
  is="image-display-control"
  src="cats.jpg"
  title="Meow"
  alt="Cats being cute"
  data-loglevel="debug"
  data-image-regions='[{
    "id": "onecatsleeping",
    "names": ["One cat sleeping"],
    "shape": "rectangle",
    "unit": "relative",
    "x": "0.042",
    "y": "0.432",
    "width": "0.248",
    "height": "0.488"
  }, {
    "id": "twocatsplaying",
    "names": ["Two cats playing"],
    "shape": "rectangle",
    "unit": "pixel",
    "imageWidth": "500",
    "imageHeight": "250",
    "x": "170",
    "y": "21",
    "width": "300",
    "height": "114"
  }]'
/>

Here the console output will start with:

[idc:cats] Populating rectangle image regions...

If not set or empty, the console output will start with:

[idc] Populating rectangle image regions...

See the attribute reference for more details.

Any changes to the id= attribute will be picked up by the web component.

Web-component-specific attributes​

Image regions are passed to the web component via the JSON-formatted data-image-regions= attribute. The component will then responsively assess which region to zoom in based on the current element size. To force the component to zoom in on a specific region, use the data-image-region-id= attribute. To disable parts or all of the web component's functionality, e.g. in order to force it to behave like a standard <img> tag, use the data-disabled= attribute. In order to control the console output, use the data-loglevel= attribute. In order to have the web component draw the image regions on top of the image as an overlay for debugging purposes, use the data-debug-draw-regions= attribute. See the attribute reference for more details and for other attributes.

Any changes to the data-* attributes will be picked up by the web component.