Generate html sizes attributes without painful for your responsive images.
Html sizes support maxDPR option to cap images dpr and speed up your website !
You can read this mozilla tutorial to understand responsive images.
This library is available on npm.
npm install html-sizes
yarn add html-sizes
pnpm add html-sizesHtml sizes provide an unique function named generateSizes.
import generateSizes from 'html-sizes';
generateSizes({
'(max-width: 340px)': '100vw',
'(min-width: 400px)': '350px',
default: '50vw',
});
// Return : (max-width: 340px) 100vw, (min-width: 400px) 350px, 50vwgenerateSizes(params: SizesParams, options?: SizesOptions);export interface SizesParams {
[key: string]: string;
default: string;
}A map (js object) with all your needed breakpoints and the required default size.
- Keys is your css breakpoints with parenthesis
- Values is your image size (with
vw,px,calc(),min(),max()...)
generateSizes respects params attributes order but default is always at the end of generated sizes.
export interface SizesOptions {
maxDPR?: MaxDPR; // 1 | 2
dpiCompatibility?: boolean;
}You can pass only 1 or 2 to cap image DPR.
This option add dpr media queries on sizes to scale down your image on high dpr devices and reduce image size.
To understand how browser pick the best image with pixel density, you can read this article from imagekit.io.
Scaling is computed on all values and all breakpoints.
Supported media queries
(min-resolution: 3dppx)(-webkit-min-device-pixel-ratio: 3)-> Safari
Examples
Simple example with a 100vw image on a 500px viewport width.
Without maxDPR
generateSizes({
default: '100vw',
});
// Return : 100vw| DPR | Sizes | Final image width |
|---|---|---|
| 1 | 100vw | 500 x 1 = 500px |
| 2 | 100vw | 500 x 2 = 1000px |
| 3 | 100vw | 500 x 3 = 1500px |
With maxDPR=2
generateSizes(
{
default: '100vw',
},
{
maxDPR: 2,
},
);
// Return : (min-resolution: 3dppx) 67vw, (-webkit-min-device-pixel-ratio: 3) 67vw, 100vw| DPR | Sizes | Final image width |
|---|---|---|
| 1 | 100vw | 500 x 1 = 500px |
| 2 | 100vw | 500 x 2 = 1000px |
| 3 | 67vw (100 * 2 / 3) | 500 x 3 x 0.67 = 1005px |
On 3x display, images is scale down to 2x.
With maxDPR=1
generateSizes(
{
default: '100vw',
},
{
maxDPR: 1,
},
);
// Return : (min-resolution: 3dppx) 34vw, (-webkit-min-device-pixel-ratio: 3) 34vw, (min-resolution: 2dppx) 50vw, (-webkit-min-device-pixel-ratio: 2) 50vw, 100vw| DPR | Sizes | Final image width |
|---|---|---|
| 1 | 100vw | 500 x 1 = 500px |
| 2 | 50vw (100 x 1 / 2) | 500 x 2 x 0.5 = 500px |
| 3 | 34vw (100 x 1 / 3) | 500 x 3 x 0.34 = 510px |
On 2x and 3x display, images is scale down to 1x.
This flag add a new supported media query with DPI for old browsers.
generateSizes(
{
'(max-width: 500px)': '100vw',
default: '500px',
},
{
maxDPR: 2,
dpiCompatibility: true,
},
);
// Return : (min-resolution: 3dppx) and (max-width: 500px) 67vw, (-webkit-min-device-pixel-ratio: 3) and (max-width: 500px) 67vw, (min-resolution: 288dpi) and (max-width: 500px) 67vw, (max-width: 500px) 100vw, (min-resolution: 3dppx) 334px, (-webkit-min-device-pixel-ratio: 3) 334px, (min-resolution: 288dpi) 334px, 500px