Skip to main content

HTML attributes and React properties

GitHub repository

Attributes and properties can be set at three different levels:

<div
  data-idc-parent
  style={{ contain: 'paint' }}
>                                   {/* on the parent DOM element */}
  <ImageDisplayControl data-debug>  {/* on the <ImageDisplayControl> component */}
    <img                            {/* on the <img>-like direct children */}
      src="https://react.frameright.io/assets/pics/skater.jpg"
      alt="Skater"
      data-avoid-no-region="off"
    />
  </ImageDisplayControl>
</div>

<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.
caution

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.

note

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="https://react.frameright.io/assets/pics/skater.jpg" alt="Skater" />
</ImageDisplayControl>

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' }}>
  <ImageDisplayControl>
    <img
      src="https://react.frameright.io/assets/pics/skater.jpg"
      alt="Skater"
    />
  </ImageDisplayControl>
</div>