@frameright/image-display-control-web-component
Advanced tools
Readme
<img is="image-display-control">An easy way to do Image Display Control in your HTML page. Made with :heart: by Frameright. Power to the pictures!
:sparkles: Live mobile demo
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://images.pexels.com/photos/3625715/pexels-photo-3625715.jpeg"
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.
This web component extends the <img> tag with the ability to accept a list of
image regions, and to zoom in on the best one for the current element size:
<img
is="image-display-control"
src="https://images.pexels.com/photos/3625715/pexels-photo-3625715.jpeg"
width="200"
height="200"
data-image-regions='[{
"id": "oneanimal",
"names": ["One animal"],
"shape": "rectangle",
"unit": "relative",
"x": "0.217",
"y": "0.708",
"width": "0.239",
"height": "0.1467"
}, {
"id": "threeanimals",
"names": ["Three animals"],
"shape": "rectangle",
"unit": "relative",
"x": "0.245",
"y": "0.725",
"width": "0.419",
"height": "0.121"
}]'
/>
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 mobile demo
img element?In order to have existing CSS rules in a project able to target indifferently
classic <img> elements and our web component, two options exist:
<img is="image-display-control" src="..."> element implementing
HTMLImageElement,
or<image-display-control><img src="..."></image-display-control> element
based on an
HTML template with a <slot> element.The problem with the second option is that it puts the <img> tag inside a new
parent element <image-display-control> and CSS rules such as
img {
/* fill the parent element */
width: 100%;
height: 100%;
}
won't have the intended results, because the parent element hasn't been instructed to fill its own parent. This would force developers to adapt their CSS rules to also target the new parent, which is not ideal.
This is why we went with the first option, which doesn't require any CSS changes in existing projects.
Nowadays an image file (e.g. JPEG, PNG) can contain this type of image regions
in their metadata according to
the IPTC standard.
The back-end would typically be responsible for extracting them from the image
file and placing them in the front-end's <img data-image-regions=" attribute.
This is for example what
this WordPress plugin
does, with the help of
a PHP library for
extracting image metadata. This can also be achieved on a Node.js back-end with
the help of
this TypeScript library.
Photographers, or anyone else, can use the Frameright app to define and store image regions in the metadata of their pictures.
Provided that you are using a bundler (e.g. Webpack or Rollup), you can add the web component to your project with:
npm install @frameright/image-display-control-web-component
or get it from a CDN:
<script
type="module"
src="https://cdn.jsdelivr.net/npm/@frameright/image-display-control-web-component@1.1.3/dist/image-display-control.min.js"
></script>
:floppy_disk: Importing in your project
<html>
<head></head>
<body>
<img
is="image-display-control"
src="https://images.pexels.com/photos/3625715/pexels-photo-3625715.jpeg"
width="200"
height="200"
data-image-regions='[{
"id": "oneanimal",
"names": ["One animal"],
"shape": "rectangle",
"unit": "relative",
"x": "0.217",
"y": "0.708",
"width": "0.239",
"height": "0.1467"
}, {
"id": "threeanimals",
"names": ["Three animals"],
"shape": "rectangle",
"unit": "relative",
"x": "0.245",
"y": "0.725",
"width": "0.419",
"height": "0.121"
}]'
/>
<!-- Built with Webpack or Rollup. Contains the web component: -->
<script src="mybundle.js"></script>
</body>
</html>
:airplane: Advanced usage
To run a local development server that serves the basic demo located in
demo/, run:
npm install
npm start
:wrench: Contributing
:sparkles: Live mobile demo
From scratch the web component should work on:
More support can be achieved with a few tweaks:
:mag: Browser support
1.1.3 (2023-05-10):
src= attribute.1.1.2 (2023-05-09):
src= attribute.1.1.1 (2023-05-09):
1.1.0 (2023-05-05):
package.json.1.0.0 (2023-05-05):
package.json.0.1.0 (2023-03-03):
data-avoid-no-region= attribute.sizes= attribute in order to avoid blinking on Chrome.0.0.9 (2023-02-20):
sizes= attribute in order to fetch
an image from the srcset= attribute that has a high enough resolution for
the region we're zooming in.0.0.8 (2023-02-16):
0.0.7 (2023-02-09):
data-css-contain-fallback= attribute.0.0.6 (2023-02-07):
0.0.5 (2023-02-07):
data-debug-draw-regions= attribute.dist/image-display-control.min.js to NPM package in order for it to
be served on CDNs like jsDelivr.data-disabled=none would be ignored.0.0.4 (2023-02-02):
0.0.3 (2023-02-02):
0.0.2 (2023-02-02):
0.0.1 (2023-02-02):
FAQs
Image Display Control Web Component
The npm package @frameright/image-display-control-web-component receives a total of 128 weekly downloads. As such, @frameright/image-display-control-web-component popularity was classified as not popular.
We found that @frameright/image-display-control-web-component demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A hospital in Mobile, Alabama, agreed to a settlement in a landmark ransomware death lawsuit, but is now reportedly reconsidering the agreement and refusing to pay.
Security News
A new report explores how advancements in LLMs are enhancing cyber threats, including polymorphic malware, personalized spearphishing, and the risk of hijacking customer service bots.
Security News
ESLint has approved an RFC that adds support for TypeScript configuration files, which is aimed at improving the developer experience and recognizing changes in the evolving JavaScript ecosystem.