rsnext/docs/basic-features/image-optimization.md

description
Next.js supports built-in image optimization, as well as third party loaders for Imgix, Cloudinary, and more! Learn more here.

Image Component and Image Optimization

Examples

• Image Component

Since version 10.0.0 Next.js has a built-in Image Component and Automatic Image Optimization.

The Next.js Image Component (next/image) is an extension of the HTML <img> element, evolved for the modern web.

The Automatic Image Optimization allows for resizing, optimizing, and serving images in modern formats like WebP. This avoids shipping large images to devices with a smaller viewport.

Image Component

To add an image to your application, import the next/image component:

import Image from 'next/image'

function Home() {
  return (
    <>
      <h1>My Homepage</h1>
      <Image
        src="/me.png"
        alt="Picture of the author"
        width={500}
        height={500}
      />
      <p>Welcome to my homepage!</p>
    </>
  )
}

export default Home

• width and height are required to prevent Cumulative Layout Shift, a Core Web Vital that Google is going to use in their search ranking
• width and height are automatically responsive, unlike the HTML <img> element
• See next/image for list of available props.

Configuration

You can configure Image Optimization by using the images property in next.config.js.

Device Sizes

You can specify a list of device width breakpoints using the deviceSizes property. Since images maintain their aspect ratio using the width and height attributes of the source image, there is no need to specify height in next.config.js – only the width. These values will be used by the browser to determine which size image should load.

module.exports = {
  images: {
    deviceSizes: [320, 420, 768, 1024, 1200],
  },
}

Image Sizes

You can specify a list of exact image widths using the imageSizes property. These widths should be different than the widths defined in deviceSizes. The purpose is for images that don't scale with the browser window, such as icons, badges, or profile images. If the width property of a next/image component matches a value in imageSizes, the image will be rendered at that exact width.

module.exports = {
  images: {
    imageSizes: [16, 32, 64],
  },
}

Domains

To enable Image Optimization for images hosted on an external website, use an absolute url for the Image src and specify which domains are allowed to be optimized. This is needed to ensure that external urls can't be abused.

module.exports = {
  images: {
    domains: ['example.com'],
  },
}

Loader

If you want to use a cloud image provider to optimize images instead of using the Next.js' built-in image optimization, you can configure the loader and path prefix. This allows you to use relative urls for the Image src and automatically generate the correct absolute url for your provider.

module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

The following Image Optimization cloud providers are supported:

• When using next start or a custom server image optimization works automatically.
• Vercel: Works automatically when you deploy on Vercel
• Imgix: loader: 'imgix'
• Cloudinary: loader: 'cloudinary'
• Akamai: loader: 'akamai'

Related

For more information on what to do next, we recommend the following sections:

next/image See all available properties for the Image component