RFC: Image Component for Next.js

[atcastle]

(Note: Edited with annotation about how the next/image component has changed during and after the course of development. Last edited 3/10/21)

This RFC describes a #proposed custom image component to be built into the Next.js framework. This is a significant addition to Next.js, and has the potential to have large impacts on application performance outcomes and developer experience.

The objective of the component is to improve performance of Next.js applications at an ecosystem level, with a particular focus on improving their Core Web Vitals scores. The component is structured around the following three primary design concerns:

The image component provides an attractive developer experience

This is listed first because the other, performance-based design concerns are only effective to the extent that people actually adopt the component and benefit from its performance optimizations. Thus, the component should be:

• Easy to use, with a concise and intuitive API.

• Easy to refactor into existing pages--it should be able to coexist on a page with regular image tags.

• Attractive as part of the new-developer experience. Getting developers using the component early will ensure that they continue to use it as they advance to larger projects.

The image component improves application performance with baked-in best practices

The main way we will improve application performance is through the integration of image-related best practices, such as the use of srcsets, preloads, and sized image assets. These practices are often not implemented, even on large Next.js applications, and can have major impacts on metrics such as LCP and CLS.

Reasons why image best practices currently aren’t followed include:

1. Developers aren’t aware of them.

2. Developers are aware of them, but implement them partially or incorrectly.

3. Developers are aware of them, but prioritize other development concerns. Following all best practices increases the amount of image-related code/markup in the codebase and imposes substantial infrastructure demands

I believe that a well-implemented image component should address all of the above obstacles. Developers will be made aware of the component due to prominent inclusion in the Next.js documentation, and the image component API will make component usage nearly as simple as using a standard img tag.

The image component precludes common performance-harming image mistakes

In analyzing many production Next.js applications, I’ve seen a lot of cases where application developers implement image-related functionality that is intended to provide a better user experience (such as image placeholders or lazy-loading), but they do so in a way that actually harms application performance. Sometimes this negative effect can be very substantial. The image component can help this problem in two ways:

1. By building in some commonly-desired functionality in a performant way, preventing developers from having to attempt to roll their own solution.

2. By integrating conformance measures that prominently warn developers when common mistakes are detected.

(Implementation Note: During the course of development, we shifted focus from warning-based conformance measures to preemptively stopping improper usage through type checking and runtime errors)

Feature Design

In this section, I’ll discuss the features of the image component that will allow it to accomplish the goals laid out in the section above.

Feature: Simple API

The image component will be able to be used much the same was as a standard img tag. The user will simply import the Image component into their page, much like the Link component is currently imported:js

import Image from 'next/image'

Then they can use it in their code like so:

<Image src=”/photos/foo.jpg” height=”1400” width=”2000” sizes=”40vw” priority>

Feature: First-class status for CDNs

One of the most noticeable things about the Image component API discussed in the section above is that the src attribute takes only a relative path, not a full URL. This is both a convenience for developers (less mark-up in their files) and also an important part of how the Image component works.

As the component is rendered, a host is selected for the image. The host provides the absolute root of the URL (for instance, the URL of your particular CDN account, or the location of your self-hosted image server), which is combined with the relative path to get the actual image location.

For a description of how the host is selected, as well as how multiple hosts are handled, see the technical details selection at the end of the RFC.

Using this system, the Image Component is agnostic to whether the application is using a CDN or self-hosted images, and it’s easy to switch image providers later on, or to have different image providers for different environments.

Since most applications at scale use CDNs or dedicated image providers, this should allow the image component to provide performance benefits to all applications, including those with the largest reach--ensuring the best overall ecosystem impact.

(Implementation note: This feature changed slightly during development. Now, instead of designating a host (such as "cloudinary") per-image, you set a single application-level host in the next.config file. If you wish to use a different host for any image, you can provide a "loader" function as a property which defines how to generate sized urls for that image)

Feature: Automatic srcsets for images

One of the most important things you can do for image performance is to use the srcset attribute to specify different versions of the image to use at different viewport sizes. This prevents the application from loading unnecessarily large image files which waste network resources and, in the case of above-the-fold images, hurts the LCP metric.

The main drawback of srcset attribute is that it requires quite a bit of additional markup and infrastructure support. The implementing developer has to make multiple versions of the image file available, and manually insert a link to each one.

The Image component addresses this drawback by automatically generating a srcset for each image, using a customizable Image Loader. The Image Loader takes a set of parameters (such as relative path, breakpoint size, and image quality) and returns a complete URL for that resource.

The intent is that most applications will use a CDN, and the loader will take advantage of those CDN’s on-demand image sizing to generate the srcset URLs. For applications which self-host images, a separate loader can be used which integrates with a custom image processing build step.

More information on loaders and self hosted images is available in the technical details section at the end of the RFC.

(Implementation note: In addition to strong support for CDNs, we expanded the support for dynamic sizing even without a CDN, through integration with the Image Optimizer)

Feature: Enforced Sizing

Another image best practice that is often ignored in the wild is that all images should have height and width attributes. These attributes give the browser the information necessary to save space for the image in the layout, even before the file transfer is completed. This prevents the layout from changing as images are downloaded, and thus strongly impacts the CLS metric.

Normal img tags do not require a size and width attribute, but the Image component will. For cases in which it’s impossible to know the size (or at least the size ratio) ahead of time, a special attribute will disable the sized requirement. In cases where the Image component is being used in a place where it’s likely to be above the fold, conformance can provide warning that use of the unsized flag will cause performance degradation.

(Implementation note: The conformance check described above was not implemented, largely because of the difficulty of detecting probable below-the-fold images at build time. Additionally, there is another case where images can be unsized: images which use the fill layout style.

Feature: Preconnect and Preloads

One of the main performance problems we see in Next.js applications is that they don’t include tags for images which appear “above the fold.” Without a preload, the network request for the image doesn’t begin until after the DOM is loaded, and the image transfer is given lower priority than the first party JavaScript.

In reality, we generally want the first few images to be downloaded with higher priority than the JavaScript, because much of the benefit of SSR or static pages is that the page can be presented, visually complete, to the user well before the application JavaScript has bootstrapped.

This has a very large impact on the LCP metric, which measures the time until the largest visible element on the page (which often includes the first large image on the page) is rendered. Properly preloading images can improve this metric on Next.js applications by 50% or more.

The image component will automatically add tags for any images which are given the priority attribute. Because this selection cannot be fully automatic and requires developer intervention, a conformance check will be added that throws a warning if a page includes elements, but none of them have the priority attribute.

The Image Component will also include  a tag for any image hosts defined in the next.config.js file.

(Implementation Note: Through experimentation, I determined the tag to be unnecessary, as long as images are properly preloaded. So that isn't in the final implementation.)

Implementation Details

CDN Support

Support for various CDNs is provided through the use of a “Loader” architecture, which allows the application to define a template for rendering a set of universal data about the image into a URL for that asset.

For instance, a loader for the Imgix platform might take something like this:

{

    path: “/photos/foo.jpg”

    quality: 70

}

And, in combination with host information from the config file, produce a URL for breakpoint width 800 that looks like

https://myApp.imgix.net/photos/foo.jpg?w=800%q=70

A Loader could easily be written for any CDN that supports those same image properties, and I expect we would ship multiple built-in loaders for common CDNs. Even if a CDN or image hosting solution doesn’t support every property provided, a Loader could be written that simply ignores the unsupported properties.

Support for self-hosted images

Though the Image component is designed with CDNs in mind, it will also work with locally hosted images. The application developer simply needs to add an image compression/resizing step into their build process, and write a custom loader that generates URLs pointing to the output paths used by that build process.

This shouldn’t be too difficult, as there are a variety of popular build tools for resizing images, and a custom loader can be as simple as a template string.

(Implementation note: This is actually much easier than described, thanks to the Image Optimizer, which provides exactly this functionality out-of-the-box for self-hosted images.)

Out-of-the-box image support for new developers

The above section discusses adding custom support for self-hosted images, but doesn’t cover the case of new developers who are trying Next.js out for the first time. We want those developers to get used to using the Image component (and getting the associated performance benefits), but obviously we can’t tell them to develop a custom image pipeline and image loader as part of the Getting Started guide.

A satisfactory solution to this problem will involve additional technology for processing and hosting images directly from the Next.js server itself. With a system for that in place, we could simply include a default Image loader that points back to an image proxy on the Next.js server, which would allow robust out-of-the-box image inclusion, without sacrificing the flexibility to use the Image component with whatever image hosting solution the application developer prefers.

That work is beyond the scope of this RFC, but I believe we will be able to coordinate development on that feature so that it’s available shortly after the release of the Image component.

Support for files from multiple sources

It’s not uncommon for an application to feature images served from multiple image hosts. The Image component will support this through an optional host attribute that lets the user specify from one of multiple hosts declared in the next.config.js file. The component will use both the host substring and the loader registered to go along with that host in constructing the URL.

If no host attribute is supplied, the default host and loader will be used.

(Implementation note: This changed somewhat. Instead of supporting multiple pre-configured hosts that you can select between with an attribute, the developer now gets one default host, and any additional hosts can be defined by passing a custom loader function to the individual image component. Commonly-used custom loaders can be managed by creating a custom image component that wraps in the custom loader. An example of that is included in the linked documentation.)

Support for one-off sources

There may be cases where the application wants to link to an externally hosted image without defining a loader for it. For these cases, we’ll need to provide access to a noOptimization attribute that tells the image component to use the URL exactly as provided and disables all loader-based features. As this will disable some of the performance benefits, conformance should warn if this usage is detected, particularly above-the-fold.

(Implementation note: The name of this attribute ended up being unoptimized.)

What about the sizes srcset property?

Unlike the srcset urls, which can be automatically generated based on the Image Loader and a static set of page breakpoints, the sizes attribute cannot be automatically determined. The best solution available to us is to pass through a sizes attribute from the Image component, and use the Image component documentation and conformance to educate developers on the importance of including sizes information.

What about background-image images?

We will recommend that people not use the background-image CSS property if it can be avoided. Most common uses of background-image (such as superimposing text over an image) can be implemented using a normal image, and performance is generally better (and definitely not worse) if developers do so. For cases that cannot reasonably be accomplished with a normal image (such as repeating background graphics), we can at least advise the developers to add the appropriate preload tags, and to in-line the CSS for above-the-fold images, for better performance.

(Implementation note: This use-case is primarily supported using the fill layout style.)

No priority images warning and dismissal

Because preloads are a major performance benefit, we want to make sure that people are actually using the priority attribute, and we should therefore provide a build-time conformance warning when we discover that:

1. There are Image component images on a page, and

2. None of those images have the priority attribute.

Of course, it’s possible for there to actually be no priority images on a page, if there is only text or other non-image content above the fold. In that case, we need to provide a way to silence the warning. I propose to do this via a field in the image section of the next.config.js file.

Images subject to additional scrutiny (initial page load + early in doc)

Some images are more likely to be performance-sensitive than others. Some specific cases:

Any image that is not visible on initial page load (for instance, because it’s a descendent of a hidden element) is not performance-sensitive.

Any image that is behind many other images is unlikely to be performance sensitive. The 8th image on the page probably is not above the fold.

Conformance checks do not need to be as stringent for images that aren’t performance sensitive. For instance, the unsized attribute should cause a build-time warning, except for images which are unlikely to be above-the-fold. Unsized images are primarily a problem for layout stability (and the CLS metric), which only matters for above-the-fold elements.

(Implementation note: This feature, as well as the preceding one were not actually included with the initial image component loadout. Ideally these will eventually be addressed soon with a runtime conformance feature)

Image element attributes

Attribute	Required?	Type	Description
height	Yes*	Number	Height of image, only used to calculate intrinsic height/width for layout reasons.
width	Yes*	Number	Height of image, only used to calculate intrinsic height/width for layout reasons.
unsized	No	N/A (flag)	Bypass requirement for width and height definition. Should cause conformance warning on performance-critical images.
priority	No	N/A (flag)	If this flag is present, adds a preload for the image
host	No	String	Use one of the registered hosts. If no host is specified, default will be used
noOptimization	No	N/A (flag)	Just use the URL as-is. Don’t do any URL transformations.

*Height and width are required unless the unsized flag is present

(Implementation note: See a final list of all property names here. Notably, the 'unsized' property was removed.)

Development Plan

Image Component v0.5

The first phase of development will be to develop a minimum viable Image Component that provides some performance benefit, so that we can quickly begin receiving feedback on the API design choices. This version will include functionality and testing for the following features:

• Basic Image component functionality with ability to include and style images on the page

• The Loader architecture for image URL generation

• host attribute

• Automatic srcset generation with sizes passthrough from the component

Estimated development time: 1-2 weeks

Image Component v0.9

This release will include the rest of the features required for the Image Component to satisfy the design considerations described in this RFC. It will include functionality and testing for the following features:

• Image preloads and preconnects with the priority attribute

• The noOptimization attribute.

• Conformance rules that warn on the following:

• No image with priority attribute

• Use of the noOptimization attribute on performance-critical images

• Performance-critical images with the unsized attribute

Estimated development time: 1-2 weeks

Image Component v1

The Image component will be ready for widespread adoption and promotion when the associated work on an integrated Next.js image hosting technology is complete. Development on that feature should be tracked alongside development of the features in the Image component itself.

[arunoda]

I'd like to see an example on how to use this with a hosted image solution like Cloudinary, Imgix, etc.
(I saw the example mentioned regarding Imgix, but looking for how it looks like in the code)

[prkagrawal]

Yeah that would be great.

[maraisr]

Wondering if a ratio is provided ahead of time, if this can be passed in instead of width/height. Our CMS gives us those fields. And by virtue of responsive design, that image probably won't be rendered at the resolution its given.

[atcastle]

Yeah, I definitely want to support using a ratio for image size. I'm still doing some experiments to figure out if Chrome and Firefox's automatic aspect ratio calculation (https://bugzilla.mozilla.org/show_bug.cgi?id=1547231, https://groups.google.com/a/chromium.org/g/blink-dev/c/hbhKRuBzZ4o/m/pmehGGHKAAAJ?pli=1) is all that's needed here, or if some additional logic needs to be baked into the component.

[giuseppeg]

@atcastle amazing RFC! Will the sizes prop match the behavior of the standard HTML attribute?

FWIW then React Native's Image component has two methods prefetch and resolveAssetSource that could be useful in user land too I suppose.

[atcastle]

Yes, sizes is meant to be basically a direct passthrough from the custom Image component to the underlying img element.

[tomevans18]

Regarding height and width, as this meta data is available at build by fetching the image could we simply “inject” these values rather than require the developer to manually enter. This would allow for incremental builds where images are added dynamically or when images are updated but the developer forgets to update the values in the code.

[timneutkens]

This would cause painfully slow production builds that can be observed in various frameworks that take this approach. The pre-providing approach works with all rendering strategies (so SSR, SSG, CSR) for example.

[xairoo]

An option is to generate a json with all the size information. This has to be done on every image change, can be done manually.

const fs = require('fs');
const path = require('path');
const glob = require('glob');
const sizeOf = require('image-size');

const imagesDir = './public/images/'; // Add a slash at the end! ./public/images/

const files = glob.sync(imagesDir + '/**/*.*');

const images = Object.assign(
	{},
	...Object.keys(files).map((index) => {
		try {
			const dimensions = sizeOf(files[index]);
			const filename = files[index].replace(imagesDir, '');
			return { [filename]: { width: dimensions.width, height: dimensions.height } };
		} catch (err) {}
	}),
);

fs.writeFileSync('src/data/images.json', JSON.stringify(images));

You just need glob and image-size
npm install glob
npm install image-size --save

And take care of the storage path fs.writeFileSync('src/data/images.json', JSON.stringify(images));

[robinglen]

Just wanted to note if this was to support srcset and preload could this also support imagesrcset on a link rel for responsive preloading images: https://web.dev/preload-responsive-images/

[atcastle]

Definitely. The intention is that when the custom Image component is used with the priority attribute, it will generate a preload link with imagesrcset generated automatically and imgsizes passed through from the user-supplied sizes attribute.

[manelmadeira]

Great RFC 🙌 What is the strategy to lazy load the images? Is this not recommend using this component?

[scott-thrillist]

I'm guessing it would be support for the loading attribute which is native to the browser, but also not as aggressive as we hoped!

[eddyw]

This is amazing! We have a custom Image that achieves the same goal. My 2cents,
It'd be great if Image attributes could include a format property. For instance, we do this:

<Image src={url} format="png" />

And this just appends [host]/theImage.svg?fmt=png to the URL. Some CDNs support providing this query param to get the image in the desired format regardless of the format it was uploaded.

[huv1k]

You can implement that with image loader

[atcastle]

Yep, like @huv1k said this would be easy to implement with an image loader. If this is a common use case for a widely-used CDN, it could be built into the default loader supplied for that CDN.

[MontoyaAndres]

I'd like to know if is possible to add the option to add background css properties.

<Image
   src="image.png"
   isBackground
/>

The prop isBackground will add the image with the property background-image, and the image will be optimized and will looks good with others background css properties. I write this because others libraries that try to do this don't have this option.

[timneutkens]

Why do you want it to be a background-image?

[MontoyaAndres]

There are some cases where I need to put a big image on the main page, the way to look better is add it as a background image, would be great if this one is optimized with this component :)

[atcastle]

We were actually talking about this a bit before I posted this RFC. background-image support is something I could see adding in a v1.1 of this feature.

To make the case for that, I'd love to hear more about why background images look better in your use case.

[eddyw]

To make the case for that, I'd love to hear more about why background images look better in your use case.

@atcastle the issue is that background-image has less priority than <img src="..." />, in other words background-image is loaded after <img>s

To optimize background-image priority, sometimes you can sort of do:

<div style="background-image: url(/bg.png)">
  <img src="/bg.png" style="pointer-events: none; opacity: 0; position: absolute;" />
  <div>Other stuff here</div>
</div>

Or something like that.

We have, for instance, Hero components that have background-image and it feels slow because <img>s load faster and the background is the last thing that appears. This helps in our case to hint the browser to download the background-image with same priority as <img>s

Another use case somewhat related to this:

<div style="background-image: url(/bg.png);background-repeat: repeat;width: 100px; height: 100px;position:relative;">
      <img src="/bg.png" style="opacity: 0; position: absolute; height: 100%; width: 100%" />
</div>

This allows to use CSS to position the image however you want and even repeat the image but the user can still click and drag the image or right click and download the image.

[MontoyaAndres]

Look this page https://aislantesyservicios.com/ the images take many time to load in phones. I'm using background-image to load them and other properties of this also. That's why I'd like to see this on this Image component :)

[huv1k]

What about different image formats support? Currently Safari is lacking support for webp. It can be solved with different sources is there any plan regarding this?

[jamesryan-dev]

+1

[sasivarnan]

Upcoming iOS 14 and macOS Big Sur will bring webp support to Safari.

Having webp support will be really appreciated .

[jescalan]

Normal img tags do not require a size and width attribute, but the Image component will. For cases in which it’s impossible to know the size (or at least the size ratio) ahead of time, a special attribute will disable the sized requirement.

I might be missing something big here, but I can't remember the last time I had a use case where hard-coding image width and height was a reasonable approach for any project, given the existence of responsive design. I feel pretty confident that if you are able to hard code an image's dimensions, and have those same dimensions work on both desktop and mobile views, that would be more of an edge case than the inverse.

Aspect ratio, on the other hand, is definitely something that could be hard-coded and would in most cases be able to persist across screen sizes. Maybe this would be a better option?

[hacknug]

I can't remember the last time I had a use case where hard-coding image width and height was a reasonable approach for any project

@jescalan I know they already cleared this out for you but I wanted to let you know mario.tours uses hardcoded size attributes to make everything work properly layout-wise (also note I'm reading a Next RFC without having used it once nor heard your pitch yet haha <3 )

[jescalan]

Oh hi @hacknug! Very reasonable, but this type of use also requires a few css attributes to make them not completely borked at any responsive size (max-width: 100%; height: auto;), and if you remove the hard coded width and height on the image element, it appears to work just as well due to the css - so I feel like despite the attributes being there, they aren't really contributing much?

[Vadorequest]

I was also confused as to why using width/height and this thread helped clear things a bit.

[rikkit]

Keep in mind that width/height are not actually the <img width="" height="" it's more like amp-img where it knows how to make it work in responsive design and automatically sizes correctly.

Did this change? When using the component it seems very clear that the values of width and height that you pass into the component determine the image size fetched from the server. I have written a wrapper for next/image that gets the available width/height on mount, and passes that into next/image.

[xairoo]

I have written a wrapper for next/image that gets the available width/height on mount, and passes that into next/image.

Will take long if you have tons of images. Check this #16832 (reply in thread)

[daneden]

This is super exciting and would definitely be another boon to the Next.js ecosystem. It would certainly replace/augment some of the makeshift solutions I have in place for my site.

One thing I’d perhaps want to see added to the RFC is detail about the resulting output, and how it may differ from client to server (for example, what sizes are generated, and what potential there is for optimising based on a client's internet connection/navigator information)

[simonireilly]

@daneden this is great, I do this too so glad I am not crazy 👍

I have pretty much the exact same thing self rolled with sharp in a number of projects so was looking at abstraction just today after reading this RFC.

When combined with the Cache-Control header this is a powerful solution for online image transformation which would be supported by server/serverless environments. It suits my use case f having hundreds of thousands of images that I don't want to pre-optimize as most may never be rendered to the page. I think this kind of implementation alludes to the RFC comment.

A satisfactory solution to this problem will involve additional technology for processing and hosting images directly from the Next.js server itself.

I think your implementation will be complementary to the RFC as it matures as well, perhaps as a default fallback online Loader 🤔

[valse]

OMG but the automatic srcsets means that I'll stop get manually the image size for each of my favorite breakpoints 😱

[valse]

At the moment I get the max widths and sizes attributes by inspecting the pages at some "main" breakpoints: for example an image could be at 50vh for the desktop resolution and 100vh from the tablet and lower... Now do you think that will it possible to automate it using puppeteer for example or similar at build time?

[kylemh]

I wanted to suggest that alt is a required prop with a developer error or dev server message saying: "An alt tag is required. If this image is purely decorative and conveys no emotional or pragmatic meaning, please pass alt an empty string."

[atcastle]

I'm very sympathetic to the desire for built-in accessibility functionality, but I think this particular check would be better done as a project-level accessibility audit or linting step, as in https://web.dev/accessibility-auditing-react/, rather than being implemented on a component-by-component basis.

edit: Of course, those tools won't work out-of-the-box with the new custom Image component in Next, but we could provide a custom ESLint rule for use alongside your existing eslint-plugin-jsx-a11y setup.

[kylemh]

True, we COULD rely on developers to setup this tooling, but I feel like Vercel / Next.js have a huge opportunity to make a very simple paradigm resolved out-of-the-box.

[stefee]

I personally am all in favour of making a lot of noise when alt text is omitted.

This sounds like an enhancement that can be discussed in a separate issue thread? It doesn't seem essential for solving the problem that this RFC solves.

[kylemh]

I think it's relevant here since an aspect of the RFC is the API surface layer the would-be component will offer, despite the fact that it's not related to performance.

[timneutkens]

@prateekbh is working on built-in support for eslint / an eslint preset for Next.js, so this could be handled as part of that, components themselves logging it out is not as ideal as an eslint rule.

[AndrewRayCode]

Webpack plugins are designed to resolve paths to static assets relative to your current file, and do things like change the host to a CDN in a production bundle. It’s unclear to me why Next hasn’t embraced this and still relies on string paths to resolve files. I’ve set up my project to use require() to ensure static asset presence. Will the features of this component work if we do
<Image src={require('../../images/image.png')} /> ?

[timneutkens]

require is commonjs which is being phased out by pretty much every tool in the ecosystem in favor of esmodules.

The majority of Next.js applications has only a few images built into the application. The majority of images are generally database-driven (CMS, ecommerce solutions, and more)

[AndrewRayCode]

Maybe this isn't the right medium, but does that mean Next.js won't support require() in the future? Or a dynamic way to resolve static assets the app needs to run (both on server and client?) other than using string paths and just hoping the asset is on disk? I'm also making the assumption that import() won't work for this case, but I don't know for sure

[AndrewRayCode]

Actually, the real question is will this component work with import png from '../img.png'; <Image src={png} />

[stefee]

This is really nice to see and I think having a next/image module with a well-designed API will be a huge net good for developers and users.

I worked recently on a solution for serving well optimised images for a statically built Vercel + Next.js site.

Here's a summary of my solution based on my particular use case, this might be useful as prior art / user story :

• Original images are stored in the GitHub repository.

• A configuration file specifies a set of rendition widths and other build parameters. [Link to config.json]

• A build script (using the sharp library) runs before every deployment and outputs a set of optimised image renditions in the source format and also WEBP format for each image. [Link to script]

• An Image React component is configured statically (using getStaticProps at the page level) using values from the same config.json file as the build script. [Link to Image.js]

• The Image component renders a <picture> tag containing an <img> which is a non-WEBP fallback source, as well as a set of <source> tags; one <source> tag for the WEBP source and then one for each other format specified in the config.json.

• The <source> and <img> tags are rendered using a couple of libraries developed by myself.

  The usage pattern and props API is very similar for both of these libraries, and it looks like this:

  import Img from '@renditions/react-img'
  
  // define a renditions configuration
  const renditions = [
    { width: '320' },
    { width: '768' },
    { width: '1280' },
  ]
  
  // define a function for getting `src` attribute for an image rendition
  const getSrc = (filename, ext, rendition) => {
    return `/images/${filename}_${rendition.width}.${ext}`
  }
  
  // define your Image component
  const Image = ({ filename, ext, alt, ...rest }) => (
    <Img
      renditions={renditions}
      getSrc={getSrc.bind(null, filename, ext)}
      alt={alt}
      autoSortRenditions
      {...rest}
    >
  )

  // use your Image component everywhere
  // and specify `size` and `breakpoints` on a per-use basis
  // for example:
  <Image
    filename="oranges"
    ext="jpg"
    size="100vw"
    breakpoints={[
      {
        mediaMinWidth: '960px',
        size: '100vw',
      },
      {
        mediaMinWidth: '480px',
        size: '50vw',
      },
    ]}
    alt="Oranges in a bowl."
    autoSortBreakpoints
  >

  The full API and source for the libraries can be found here:

  • @renditions/react-img
  • @renditions/react-picture-source

  Under the hood they use these helpers for generating sizes and srcset:

  • @renditions/get-sizes
  • @renditions/get-srcset

• The build script also gets the width and height metadata of each image and stores it in a images-dist/metadata.json that the application can read (during getStaticProps) and use for rendering width and height attributes on the <img> tag.

• I also pass through loading="lazy" prop to the component at the call site for native lazy loading of below-the-fold images. [Link to example of native lazy loading]

---

There is quite a lot of different parts to what I've written here in describing my use case and solution, and not all of the things on this list are in the scope of this RFC, but I kept them in anyway since they are at least tangentially relevant (and therefore should somewhat inform the API design).

I will give some thought to how the solution described in this RFC would apply to my use case described above, and will write in this thread if I can think of anything that might prevent me from switching to using a next/image module instead of my current solution – nothing obvious comes to mind.

If there are any parts of my solution that you think are nice then please feel free to steal my ideas. (The size/breakpoints props API comes to mind, I think this is a nice abstraction over the sizes attribute that Next.js could adopt as well although it probably needs some refinement and very careful thought).

[atcastle]

Awesome, I'll take a look at your repo. In general, it looks like your solution is a little broader, in that it also covers the build pipeline stuff. I think that will be coming to Next.js, but it's not part of this specific RFC.

[stefee]

Cheers. My intention with laying all the parts out (including build pipeline) was that these should all be part of the equation when it comes to designing the API for a generic image component.

[rokinsky]

1. Why didn't you use <picture /> with <source /> tags for different image types?
2. It seems to me that images are not crawlable: deferred images will have data-src instead of src. You could use <noscript />, native lazy-loading + polyfills, or something else.

[wis]

also the images are not cacheable by a CDN.
or as cacheable, if the dynamic response had a Vary: accept header the pull CDN can cache it but the cache hit ratio would be really low, because there are a lot of "accept" headers for different browsers out there.
was the <img> element chosen over <picture> because Next.js supports IE? I think the picture element fallbacks to the <img> tag inside it on IE.
edit: the srcset attribute on <img> is also not supported in IE, and the browser fallbacks to src.

[kripod]

Great work on this proposal and the implementation! 🙌

Is there an idiomatic way to support high density displays? I’m currently using the following “hack” for 2x until a better solution arises:

/* next.config.js */
module.exports = {
  images: {
    deviceSizes: [640, 1024, 1440, 1920]
      .flatMap((width) =>
        // Support high pixel density displays
        [width, 2 * width],
      )
    .sort(),
  },
};

[eddyw]

I just saw a merged PR that updates the default config to handle 2x/3x DPI https://github.com/vercel/next.js/pull/18717/files

It's just an array so it's a completely valid solution to use flatMap if you're manually providing the values. Also, I saw from the code in Image.tsx component that the deviceSizes and imageSizes get sorted in place, so you don't actually need to sort it in your config (that'd save you 10 bytes removing .sort(), 😝 )

[luknl]

Hey, does anyone encounter this problem when migrating from 10.0.0 to 10.0.1?

[pueyo5]

Is there a solution for using completely different images for different layouts?

My current code:

        <picture>
          <source
            srcSet={`${backgroundUrl}/landing-bg-375px,
                ${backgroundUrl}/landing-bg-375px_2x 2x`}
            media="(max-width: 575px)"
          />
          <source
            srcSet={`${backgroundUrl}/landing-bg-768px,
                ${backgroundUrl}/landing-bg-768px_2x 2x`}
            media="(max-width: 1023px)"
          />
          <source
            srcSet={`${backgroundUrl}/landing-bg-1024px,
                ${backgroundUrl}/landing-bg-1024px_2x 2x`}
            media="(max-width: 1440px)"
          />
          <source
            srcSet={`${backgroundUrl}/landing-bg-1440px,
                ${backgroundUrl}/landing-bg-1440px_2x 2x`}
          />
          <img alt={`background ${landing}`} src={`${backgroundUrl}/landing-bg-768px`} />
        </picture>

[ShanonJackson]

just have two image components where they display: none display: inline-block based off media query?

<Image className={styles.mobile} src={"/mobile-image"}/>
<Image className={styles.desktop} src={"/desktop-image"}/>

[Elia-Darwish]

Just a small note:

Having display none on the image does not normally prevent it from being downloaded. And it’s usually recommended to use either a picture tag, or JavaScript to switch the image src.

However, if you are using the Image component and it’s being lazy loaded, the intersection observer will not detect the hidden image and the image will not load until it’s visible!

[josebrito]

I've faced the same issue and solved it with react-media. I recommend some sort of strategy to fill in the defaultMatches prop, to prevent both images from being downloaded if media query does not match on first load.

import Media from 'react-media';

<Media query={devices.md} defaultMatches={isThisALargeDevice()}>
        {(isLargeDevice) => (
          <Image
            alt={props.alt}
            src={isLargeDevice ? props.largeImageSrc : props.smallImageSrc}
            {...someOtherProps}
          />
        )}
</Media>

However, it would be great if Image component supported <picture> tags.

[franklinhardt]

totally agree that next/image should provide an option to reference different sources for breakpoints. only serving auto-compressed versions of the same source is definitively not enough for responsive layouts that may require multiple images with different ratio or motives for different device sizes.

[curiolearner]

Using 10.0.1, I tried using apollo graphql to test against Next 10's fetching from AWS S3. bucket. As most of the time I use bootstrap variants, I substituted reactstrap's CardImg with Image. The S3 bucket had already resized images categorized by size. Without programmatically picking the right size for the view size, the CardImg will retireve the original size and then subsequent visit will get from the Cache. On the other hand, the Next's will do the magic to resize to the view and will use webp. But it does not cache. There will be always network access compared to the former case. Can someone advise if using Next10 Image:
a) Does one have to implement own caching? How can I use the InCache of apollo together with Image?
b) The caching seems to have better fetching cost and user experience. If a balanced cost ( ie cost of storing multiple images vs cost of on-demand resizing ), what is a better way to implement?
c) Most of the time, reactstrap, react-bootstrap and others are use. For example, we may use Card with CardImg and its variants. How do we use together with these frameworks?
Appreciate any advice. thanks

[raczosala]

are regular expressions currently supported in domains configuration?

[coodoo]

Wondering what's the story for SSR support of next/image component? Meaning will the images be visible to a crawler?