Image Display Control React Component
➡️ See this document rendered at docs.frameright.io/react
An easy way to do Image Display Control in your React
web app. Made with :heart: by Frameright. Power
to the pictures!
Less than 5kB in your final client-side bundle.
:sparkles: Live demo
💻 CodeSandbox
Table of Contents
Overview
This React component extends any <img>
-like element/component with the ability
to retrieve Image Display Control metadata from its image file in order to
automatically and responsively zoom in on the most interesting part of the
image.
It integrates nicely with other advanced features you may be using in your
existing project, e.g.:
It doesn't change the structure of your DOM: your existing CSS rules still
apply.
:sparkles: Live demo
:bulb: GitHub Discussions
NOTE: if you are not using React, you may want to have a look at the
Image Display Control Web component
instead.
Without this component
When an image is too big for its <img>
HTML element, the best option browsers
offer nowadays is to use the
object-fit: cover;
CSS property in order to scale and middle-crop it:
<img
src="https://react.frameright.io/assets/pics/skater.jpg"
width="200"
height="200"
style="object-fit: cover;"
/>
This is less than optimal, as there might be, in the example above, a better
square-ish region in the image that could be displayed instead of the
middle-crop.
Basic usage
This React component extends its <img>
-like children with the ability to
retrieve image regions from their image metadata, and to zoom in on the best one
for the current element size:
<ImageDisplayControl>
<img
src="https://react.frameright.io/assets/pics/skater.jpg"
width="200"
height="200"
/>
</ImageDisplayControl>
The resulting HTML element is responsive and will automatically reassess the
best region to zoom in on when it gets resized, e.g. when the user turns their
phone from portrait to landscape.
:sparkles: Live demo
💻 CodeSandbox
:bulb: GitHub Discussions
Image Display Control metadata
Nowadays an image file (e.g. JPEG, PNG) can contain this type of image regions
in their metadata according to
the IPTC standard.
This React component uses
a library
to let the back-end or front-end extract the regions from the image file. It
then passes them to the <img>
tag and turns it into
a web component,
which automatically and responsively zooms in on the best region.
Photographers, or anyone else, can use the
Frameright webapp to define and store image regions in
the metadata of their pictures.
Installation
In your Node.js-based project (e.g. using Next.js or
Vite) run:
npm install @frameright/react-image-display-control
Less than 5kB in your final client-side bundle.
:floppy_disk:
Importing in your project
Usage
import { ImageDisplayControl } from "@frameright/react-image-display-control";
export default function MyComponent() {
return (
<ImageDisplayControl>
<img
src="https://react.frameright.io/assets/pics/skater.jpg"
width="200"
height="200"
/>
</ImageDisplayControl>
);
}
This doesn't change the structure of the resulting DOM, i.e.:
- the
<img>
tag remains an <img>
tag, and - no new parent elements are added around it, so
- the CSS rules that used to target the
<img>
tag directly will still apply,
and - the
<img>
tag will still naturally take the same space and position in the
layout.
Other <img>
-like elements/components are supported as well, e.g.
Next.js <Image>
s or
React-Bootstrap <Image>
s.
:airplane:
Advanced usage
🌍
Supported environments
:wrench: Contributing
📝 Changelog
:sparkles: Local demo
:bulb: GitHub Discussions
:sparkles: Live demo
🙏
Dependency tree / credits