Skip to main content

HTML attributes and React properties

GitHub repository

Attributes and properties can be set at three different levels:

style={{ contain: 'paint' }}
> {/* on the parent DOM element */}
<ImageDisplayControl data-debug> {/* on the <ImageDisplayControl> component */}
<img {/* on the <img>-like direct children */}

<img>-like children's attributes and properties

Standard attributes and properties

Keep using the attributes and properties of the child as you would otherwise, whether it is a stock <img> element or, for example, a Next.js <Image> component. With a few caveats:

src= attribute

The src= attribute is supported and mandatory. The <ImageDisplayControl> component will read it:

  • in order to determine if the child is an <img>-like child,
  • in order to parse the image's metadata containing the Image Regions.

If the src= attribute points to another domain as the one hosting the page, make sure that the server hosting the image allows CORS.

is= attribute

The <ImageDisplayControl> component will set the is="image-display-control" attribute on all its <img>-like direct children, in order to turn them into Image Display Control web components.

sizes= and style= attributes

The web component will then responsively tweak the sizes= and style= attributes in the browser, extending anything you might have already set. See the web component's attribute documentation for more details.


We are setting suppressHydrationWarning on the <ImageDisplayControl> component, so that React does not complain about the underlying DOM being tweaked.

class= and className= properties

We support both the standard class= attribute and the React className= property.

Additional attributes and properties

Standard web component data-*= attributes

Any of the web-component-specific data-*= attributes are supported. See the web component's attribute reference for more details.

data-image-regions= attribute

This attribute is used for passing a list of Image Regions to the web component. You don't have set it: the <ImageDisplayControl> component will do it for you by parsing the Image Regions from the image pointed to by the src= attribute.

You may however set it yourself, if you want, in order to override the Image Regions that would otherwise be parsed from the image metadata.

Additional properties

Some more properties on the children are being written or read by the <ImageDisplayControl> component.

data-path-on-server= property

Use this property to indicate the path of the image file on the server, in order to make server-side rendering possible. See server-side rendering for more details.

Internal properties

At the moment the <ImageDisplayControl> component sets the following properties on its children for internal purposes:

  • ref=
  • data-idc-uuid=
  • data-src-prop=

This is subject to change. Do not read or write these properties yourself.

ImageDisplayControl component's properties

You can set the data-debug boolean property to true on the <ImageDisplayControl> component in order to enable debugging traces in the browser's console and, if applicable, in the server's logs (during server-side rendering) or in the build logs (during static site generation).

This would look like:

<ImageDisplayControl data-debug>
<img src="" alt="Skater" />

Parent DOM element's attributes

By default the Image Display Control web component will add contain: paint; to the style= attribute of its parent DOM element. This is called CSS containment and is used to avoid unwanted scrollbars.

Because of this, React may notice that the DOM has been tweaked and complain with a cryptic warning in the browser's console. To avoid this, you can either:

To show that you understand, please also set the data-idc-parent boolean property to true on that element. Otherwise, the <ImageDisplayControl> component will print a friendly warning to point you to this documentation.

This would look like:

<div data-idc-parent style={{ contain: 'paint' }}>