Next.js plugin for embedding optimized images.

  • import png/jpg images
  • output to webp format
  • resize to multiple screen sizes and densities
  • optimize webp and fallback images using sharp
  • lazy load in modern browsers with prop forwarding (loading="lazy")
  • prevent layout shift with automatic width/height attributes
  • streamlined usage with the built in <Picture /> component
  • art direction with different images for different breakpoints
  • fast deployment and development workflow using persistent cache

Examples

  1. One size per breakpoint
  2. Override breakpoints
  3. Override sizes attribute
  4. Single image
  5. Art direction
  6. Exact image sizes
  7. PNG images
  8. Other query params and component props

One size per breakpoint

The most typical usage. Provide one image per each device size you're targeting. For example, if you're targeting small/large at 768px breakpoint (as configured in your next.config.js), provide 2 sizes. If you're targeting mobile/tablet/desktop with breakpoints 480px and 768px (as configured in your next.config.js) - provide 3 sizes, and so on.

<Picture src={require('../images/coffee1.jpg?sizes=375,860')} />

Output

<picture>
    <source
        type="image/webp"
        srcSet="/next-img/_next/static/images/coffee1-375@1x-f1dc5dc288aa4461.webp 375w,
                /next-img/_next/static/images/coffee1-375@2x-4bb30d5cb8b57f76.webp 750w,
                /next-img/_next/static/images/coffee1-860@1x-e5df48f42a326173.webp 860w,
                /next-img/_next/static/images/coffee1-860@2x-cc59476c8e22c394.webp 1720w"
        sizes="(max-width: 768px) 375px, 860px"
    />
    <source
        type="image/jpeg"
        srcSet="/next-img/_next/static/images/coffee1-375@1x-eef43d972bb2cea9.jpg 375w,
                /next-img/_next/static/images/coffee1-375@2x-afaa0eef3fd9d620.jpg 750w,
                /next-img/_next/static/images/coffee1-860@1x-5fd4aa9720369a82.jpg 860w,
                /next-img/_next/static/images/coffee1-860@2x-b4530e6ddf963a73.jpg 1720w"
        sizes="(max-width: 768px) 375px, 860px"
    />

    <img
        src="/next-img/_next/static/images/coffee1-375@1x-eef43d972bb2cea9.jpg"
        srcSet="/next-img/_next/static/images/coffee1-375@1x-eef43d972bb2cea9.jpg 375w,
                /next-img/_next/static/images/coffee1-375@2x-afaa0eef3fd9d620.jpg 750w,
                /next-img/_next/static/images/coffee1-860@1x-5fd4aa9720369a82.jpg 860w,
                /next-img/_next/static/images/coffee1-860@2x-b4530e6ddf963a73.jpg 1720w"
        width="375"
        height="250"
    />
</picture>

Override breakpoints

You can specify a different set of breakpoints for an individual image. Let's say your preconfigured breakpoints are [768], but for some image you want to use 3 sizes at breakpoints [768, 1080].

<Picture
  src={require('../images/coffee2.jpg?sizes=375,600,860')}
  breakpoints={[768,1080]}
/>

Output

<picture>
    <source
        type="image/webp"
        srcSet="/next-img/_next/static/images/coffee2-375@1x-32bb737aec2a5cea.webp 375w,
                /next-img/_next/static/images/coffee2-375@2x-383afe7ab9db9367.webp 750w,
                /next-img/_next/static/images/coffee2-600@1x-53dceab7a7b4c416.webp 600w,
                /next-img/_next/static/images/coffee2-600@2x-048f202979927632.webp 1200w,
                /next-img/_next/static/images/coffee2-860@1x-0810827a3694ce79.webp 860w,
                /next-img/_next/static/images/coffee2-860@2x-a87ecbdf5b7571f1.webp 1720w"
        sizes="(max-width: 768px) 375px, (max-width: 1080px) 600px, 860px"
    />
    <source
        type="image/jpeg"
        srcSet="/next-img/_next/static/images/coffee2-375@1x-f022b1891963f70c.jpg 375w,
                /next-img/_next/static/images/coffee2-375@2x-a4045ceb87ae9421.jpg 750w,
                /next-img/_next/static/images/coffee2-600@1x-c4e0c08b826afd36.jpg 600w,
                /next-img/_next/static/images/coffee2-600@2x-9e5108197ce7f917.jpg 1200w,
                /next-img/_next/static/images/coffee2-860@1x-41a43255eb427ac6.jpg 860w,
                /next-img/_next/static/images/coffee2-860@2x-cf4d474015fbd005.jpg 1720w"
        sizes="(max-width: 768px) 375px, (max-width: 1080px) 600px, 860px"
    />

    <img
        src="/next-img/_next/static/images/coffee2-375@1x-f022b1891963f70c.jpg"
        srcSet="/next-img/_next/static/images/coffee2-375@1x-f022b1891963f70c.jpg 375w,
                /next-img/_next/static/images/coffee2-375@2x-a4045ceb87ae9421.jpg 750w,
                /next-img/_next/static/images/coffee2-600@1x-c4e0c08b826afd36.jpg 600w,
                /next-img/_next/static/images/coffee2-600@2x-9e5108197ce7f917.jpg 1200w,
                /next-img/_next/static/images/coffee2-860@1x-41a43255eb427ac6.jpg 860w,
                /next-img/_next/static/images/coffee2-860@2x-cf4d474015fbd005.jpg 1720w"
        width="375"
        height="250"
    />
</picture>

Override sizes attribute

Use the sizes prop in order to get full control over specifying which image should be used at what breakpoint. This way you can specify any number of image sizes and choose to show them at any breakpoint.

<Picture
  src={require('../images/coffee3.jpg?sizes=375,600,860')}
  sizes='(max-width: 768px) 100vw, (max-width: 1180px) 600px, 860px'
/>

Output

<picture>
    <source
        type="image/webp"
        srcSet="/next-img/_next/static/images/coffee3-375@1x-0519abd6ea2b4853.webp 375w,
                /next-img/_next/static/images/coffee3-375@2x-00d7bb204b79da6e.webp 750w,
                /next-img/_next/static/images/coffee3-600@1x-b8f4ddeaa6403ad9.webp 600w,
                /next-img/_next/static/images/coffee3-600@2x-0c3ff04a62d272bc.webp 1200w,
                /next-img/_next/static/images/coffee3-860@1x-94f73a5618f9e91a.webp 860w,
                /next-img/_next/static/images/coffee3-860@2x-f4c401d722635764.webp 1720w"
        sizes="(max-width: 768px) 100vw, (max-width: 1180px) 600px, 860px"
    />
    <source
        type="image/jpeg"
        srcSet="/next-img/_next/static/images/coffee3-375@1x-e76089f12e23a13f.jpg 375w,
                /next-img/_next/static/images/coffee3-375@2x-ddec551a6a96f9c4.jpg 750w,
                /next-img/_next/static/images/coffee3-600@1x-c34e7415f0172700.jpg 600w,
                /next-img/_next/static/images/coffee3-600@2x-08da1660856cc45a.jpg 1200w,
                /next-img/_next/static/images/coffee3-860@1x-be5f5cdcb3b2589d.jpg 860w,
                /next-img/_next/static/images/coffee3-860@2x-faec02a1b67f65ae.jpg 1720w"
        sizes="(max-width: 768px) 100vw, (max-width: 1180px) 600px, 860px"
    />

    <img
        src="/next-img/_next/static/images/coffee3-375@1x-e76089f12e23a13f.jpg"
        srcSet="/next-img/_next/static/images/coffee3-375@1x-e76089f12e23a13f.jpg 375w,
                /next-img/_next/static/images/coffee3-375@2x-ddec551a6a96f9c4.jpg 750w,
                /next-img/_next/static/images/coffee3-600@1x-c34e7415f0172700.jpg 600w,
                /next-img/_next/static/images/coffee3-600@2x-08da1660856cc45a.jpg 1200w,
                /next-img/_next/static/images/coffee3-860@1x-be5f5cdcb3b2589d.jpg 860w,
                /next-img/_next/static/images/coffee3-860@2x-faec02a1b67f65ae.jpg 1720w"
        width="375"
        height="240"
    />
</picture>

Single image

You can leave out the sizes query param altogether. That will load the original image size across any device width. Note, this still outputs an image per screen density and shows the appropriate one based on the device.

<Picture src={require('../images/coffee4.jpg')} />

Output

<picture>
    <source
        type="image/webp"
        srcSet="/next-img/_next/static/images/coffee4-1720@1x-18951e5e2accf200.webp 1720w,
                /next-img/_next/static/images/coffee4-1720@2x-18951e5e2accf200.webp 1720w"
        sizes="1720px"
    />
    <source
        type="image/jpeg"
        srcSet="/next-img/_next/static/images/coffee4-1720@1x-a952bf70e984111d.jpg 1720w,
                /next-img/_next/static/images/coffee4-1720@2x-a952bf70e984111d.jpg 1720w"
        sizes="1720px"
    />

    <img
        src="/next-img/_next/static/images/coffee4-1720@1x-a952bf70e984111d.jpg"
        srcSet="/next-img/_next/static/images/coffee4-1720@1x-a952bf70e984111d.jpg 1720w,
                /next-img/_next/static/images/coffee4-1720@2x-a952bf70e984111d.jpg 1720w"
        width="1720"
        height="1227"
    />
</picture>

Art direction

You can pass an array of images to the src. This way you can show an entirely different image at each breakpoint. This changes the html output to switch between the images using the html media attribute. Note, you can take this even further by specifying multiple sizes for each image and using the sizes propto specify what should be shown when.

<Picture
  src={[
    require('../images/coffee5-s.jpg?sizes=375'),
    require('../images/coffee5-m.jpg?sizes=600'),
    require('../images/coffee5-l.jpg?sizes=860'),
  ]}
  breakpoints={[768, 1180]}
/>

Output

<picture>
    <source
        type="image/webp"
        srcSet="/next-img/_next/static/images/coffee5-s-375@1x-fef2e427ef89ad09.webp 375w,
                /next-img/_next/static/images/coffee5-s-375@2x-527a9fe664ff0b15.webp 750w"
        sizes="375px"
        media="(max-width: 768px)"
    />
    <source
        type="image/jpeg"
        srcSet="/next-img/_next/static/images/coffee5-s-375@1x-8ddfebd307018343.jpg 375w,
                /next-img/_next/static/images/coffee5-s-375@2x-18caa8321345bafd.jpg 750w"
        sizes="375px"
        media="(max-width: 768px)"
    />
    <source
        type="image/webp"
        srcSet="/next-img/_next/static/images/coffee5-m-600@1x-9b47222af09ea8de.webp 600w,
                /next-img/_next/static/images/coffee5-m-600@2x-5a43fb5e849863de.webp 1200w"
        sizes="600px"
        media="(max-width: 1180px)"
    />
    <source
        type="image/jpeg"
        srcSet="/next-img/_next/static/images/coffee5-m-600@1x-25caafe9690d38b9.jpg 600w,
                /next-img/_next/static/images/coffee5-m-600@2x-4444e258ab1cf37c.jpg 1200w"
        sizes="600px"
        media="(max-width: 1180px)"
    />
    <source
        type="image/webp"
        srcSet="/next-img/_next/static/images/coffee5-l-860@1x-3819f22d978168d2.webp 860w,
                /next-img/_next/static/images/coffee5-l-860@2x-2b6882db1bd73773.webp 1720w"
        sizes="860px"
    />
    <source
        type="image/jpeg"
        srcSet="/next-img/_next/static/images/coffee5-l-860@1x-0eb8a2a052338b41.jpg 860w,
                /next-img/_next/static/images/coffee5-l-860@2x-ca645a76d0141529.jpg 1720w"
        sizes="860px"
    />

    <img
        src="/next-img/_next/static/images/coffee5-s-375@1x-8ddfebd307018343.jpg"
        srcSet="/next-img/_next/static/images/coffee5-s-375@1x-8ddfebd307018343.jpg 375w,
                /next-img/_next/static/images/coffee5-s-375@2x-18caa8321345bafd.jpg 750w"
    />
</picture>

Exact image sizes

By default, every image gets translated to 1x and 2x densities. That is, if you display the image in the browser at 800px width, then specifying ?sizes=800 will produce and show 800px wide image for low density devices and 1600px wide image for high density devices. If you'd like, however, you can specify any number of exact sizes by setting densities to 1x.

<Picture src={require('../images/coffee6.jpg?sizes=300,600,900,1200,1500&densities=1x')} sizes='100vw' />

Output

<picture>
    <source
        type="image/webp"
        srcSet="/next-img/_next/static/images/coffee6-300@1x-1c455bda448b2e6c.webp 300w,
                /next-img/_next/static/images/coffee6-600@1x-a6964b9ccffa63ec.webp 600w,
                /next-img/_next/static/images/coffee6-900@1x-55f7987888c5f131.webp 900w,
                /next-img/_next/static/images/coffee6-1200@1x-98f564fdfb0e739c.webp 1200w,
                /next-img/_next/static/images/coffee6-1500@1x-6c4be087ed783da0.webp 1500w"
        sizes="100vw"
    />
    <source
        type="image/jpeg"
        srcSet="/next-img/_next/static/images/coffee6-300@1x-49a5873d687d657f.jpg 300w,
                /next-img/_next/static/images/coffee6-600@1x-1bf8c9e8a9324d23.jpg 600w,
                /next-img/_next/static/images/coffee6-900@1x-ab791bfbcdf3142e.jpg 900w,
                /next-img/_next/static/images/coffee6-1200@1x-886e112d63dd7076.jpg 1200w,
                /next-img/_next/static/images/coffee6-1500@1x-6dcefebf5774255c.jpg 1500w"
        sizes="100vw"
    />

    <img
        src="/next-img/_next/static/images/coffee6-300@1x-49a5873d687d657f.jpg"
        srcSet="/next-img/_next/static/images/coffee6-300@1x-49a5873d687d657f.jpg 300w,
                /next-img/_next/static/images/coffee6-600@1x-1bf8c9e8a9324d23.jpg 600w,
                /next-img/_next/static/images/coffee6-900@1x-ab791bfbcdf3142e.jpg 900w,
                /next-img/_next/static/images/coffee6-1200@1x-886e112d63dd7076.jpg 1200w,
                /next-img/_next/static/images/coffee6-1500@1x-6dcefebf5774255c.jpg 1500w"
        width="300"
        height="200"
    />
</picture>

PNG images

PNG images are supported as well. In this case, a lossless webp is outputted by default.

<Picture src={require('../images/illustration.png?sizes=480,860')} />

Output

<picture>
    <source
        type="image/webp"
        srcSet="/next-img/_next/static/images/illustration-480@1x-2d81ddfb22d53bad.webp 480w,
                /next-img/_next/static/images/illustration-480@2x-c2553c2ab0e0c073.webp 960w,
                /next-img/_next/static/images/illustration-860@1x-5640f75aa697e0f0.webp 860w,
                /next-img/_next/static/images/illustration-860@2x-ca2511ccfe0de289.webp 1344w"
        sizes="(max-width: 768px) 480px, 860px"
    />
    <source
        type="image/png"
        srcSet="/next-img/_next/static/images/illustration-480@1x-b1aca9c1b210e6cf.png 480w,
                /next-img/_next/static/images/illustration-480@2x-c190ab3ede674ffc.png 960w,
                /next-img/_next/static/images/illustration-860@1x-6ffb440d07835e96.png 860w,
                /next-img/_next/static/images/illustration-860@2x-bf2fc15ac1ad850c.png 1344w"
        sizes="(max-width: 768px) 480px, 860px"
    />

    <img
        src="/next-img/_next/static/images/illustration-480@1x-b1aca9c1b210e6cf.png"
        srcSet="/next-img/_next/static/images/illustration-480@1x-b1aca9c1b210e6cf.png 480w,
                /next-img/_next/static/images/illustration-480@2x-c190ab3ede674ffc.png 960w,
                /next-img/_next/static/images/illustration-860@1x-6ffb440d07835e96.png 860w,
                /next-img/_next/static/images/illustration-860@2x-bf2fc15ac1ad850c.png 1344w"
        width="480"
        height="257"
    />
</picture>

Other query params and component props

You can control image quality and densities in addition to specifying the sizes when importing an image. See README for full details. You can pass extra props to the Picture component, these will be forwarded to the underlying image element. This is useful for adding lazy loading, class names, and so on.

<Picture
  src={require('../images/coffee7.jpg?sizes=375,860&jpeg[quality]=10&jpeg[webp][quality]=10')}
  className='coffee'
  data-demo='coffee'
  alt='Three cups of coffee with different amounts of milk'
  loading='lazy'
/>

Output

<picture>
    <source
        type="image/webp"
        srcSet="/next-img/_next/static/images/coffee7-375@1x-bc9e2408c3a5b213.webp 375w,
                /next-img/_next/static/images/coffee7-375@2x-267e958b34a50748.webp 750w,
                /next-img/_next/static/images/coffee7-860@1x-7d9b407e58e0c9bf.webp 860w,
                /next-img/_next/static/images/coffee7-860@2x-b91d08c9393cf3a0.webp 1720w"
        sizes="(max-width: 768px) 375px, 860px"
    />
    <source
        type="image/jpeg"
        srcSet="/next-img/_next/static/images/coffee7-375@1x-9546dd70fd9ef4f1.jpg 375w,
                /next-img/_next/static/images/coffee7-375@2x-3b0ebc6984575f3a.jpg 750w,
                /next-img/_next/static/images/coffee7-860@1x-dc17af338f7bb70c.jpg 860w,
                /next-img/_next/static/images/coffee7-860@2x-7d3a7e3d23d59e4a.jpg 1720w"
        sizes="(max-width: 768px) 375px, 860px"
    />

    <img
        class="coffee"
        data-demo="coffee"
        alt="Three cups of coffee with different amounts of milk"
        loading="lazy"
        src="/next-img/_next/static/images/coffee7-375@1x-9546dd70fd9ef4f1.jpg"
        srcSet="/next-img/_next/static/images/coffee7-375@1x-9546dd70fd9ef4f1.jpg 375w,
                /next-img/_next/static/images/coffee7-375@2x-3b0ebc6984575f3a.jpg 750w,
                /next-img/_next/static/images/coffee7-860@1x-dc17af338f7bb70c.jpg 860w,
                /next-img/_next/static/images/coffee7-860@2x-7d3a7e3d23d59e4a.jpg 1720w"
        width="375"
        height="252"
    />
</picture>
Three cups of coffee with different amounts of milk