Image

Framework Next.js 13 Image
Categories:
Tags:

next/image

// app/page.js
import Image from 'next/image';

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  );
}

next/image properties

Prop Example Type Required
src src="/profile.png" String Yes
width width={500} Integer (px) Yes
height height={500} Integer (px) Yes
alt alt="Picture of the author" String Yes
loader loader={imageLoader} Function -
fill fill={true} Boolean -
sizes sizes="(max-width: 768px) 100vw" String -
quality quality={80} Integer (1-100) -
priority priority={true} Boolean -
placeholder placeholder="blur" String -
style style={{objectFit: "contain"}} Object -
onLoadingComplete onLoadingComplete={img => done())} Function -
onLoad onLoad={event => done())} Function -
onError onError(event => fail()} Function -
loading loading="lazy" String -
blurDataURL blurDataURL="data:image/jpeg..." String -

Required Props

The Image Component requires the following properties:

  • src
  • width
  • height
  • and
// app/page.js
import Image from 'next/image';

export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Picture of the author"
      />
    </div>
  );
}

src

Must be one of the following:

  • A locally imported image file. Or,
  • A path string. This can be either an external URL or an internal path.

width

  • This property is required
  • EXCEPT for local images or images with the fill property.

height

  • This property is required
  • EXCEPT for local images or images with the fill property.

alt

The alt property is used to describe the image for screen readers and search engines. It is also the fallback text if images have been disabled or an error occurs while loading the image.

loader

A custom function used to resolve image URLs.

A loader is a function that returns a URL string for the image, it accepts the following parameters:

  • src
  • width
  • quality
import Image from 'next/image';

const imageLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`;
};

export default function Page({ imageLoader }) {
  return (
    <Image
      loader={imageLoader}
      src="/me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  );
};

fill

fill={true} // {true} | {false}

A boolean that causes the image to fill the parent element instead of setting width and height.

By default, the img element will automatically be assigned the position: "absolute" style.

The parent element must assign position: "relative", position: "fixed", or position: "absolute" style.

<div style="position:relative">
  <Image
    src="/me.png"
    alt="Picture of the author"
    fill={true}
  />
</div>

The default image fit behavior will stretch the image to fit the container.

You may prefer to set object-fit: "contain" for an image which is letterboxed to fit the container and preserve aspect ratio.

Alternatively, object-fit: "cover" will cause the image to fill the entire container and be cropped to preserve aspect ratio. For this to look correct, the overflow: "hidden" style should be assigned to the parent element.

style

Allows passing CSS styles to the underlying image element.

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #666',
};

export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />;
}

sizes

A string that provides information about how wide the image will be at different breakpoints.

The value of sizes will greatly affect performance for images using fill or which are styled to have a responsive size.

import Image from 'next/image';

export default function Page() {
  <div className="grid-element">
    <Image
      fill={true}
      src="/example.png"
      sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
    />
  </div>;
}

quality

quality={75} // {number 1-100}

The quality of the optimized image, an integer between 1 and 100, where 100 is the best quality and therefore largest file size. Defaults to 75.

priority

priority={false} // {false} | {true}

When true, the image will be considered high priority and preload. Lazy loading is automatically disabled for images using priority.

placeholder

placeholder = 'empty'; // {empty} | {blur}

A placeholder to use while the image is loading. Possible values are blur or empty. Defaults to empty.

When using blur, the blurDataURL property will be used as the placeholder.

If src is a local image and the imported image is .jpg, .png, .webp, or .avif, then blurDataURL will be automatically populated.

For dynamic images, you MUST provide the blurDataURL property. Solutions such as Plaiceholder can help with base64 generation.

loading

The loading behavior of the image. Defaults to lazy.

loading = 'lazy'; // {lazy} | {eager}
Options Description
lazy Defer loading the image until it reaches a calculated distance from the viewport.
eager Load the image immediately

unoptimized

When true, the source image will be served as-is instead of changing quality, size, or format. Defaults to false.

unoptimized = {false} // {false} | {true}

This prop can also be assigned to all images by updating next.config.js with the following configuration:

// next.config.js
module.exports = {
  images: {
    unoptimized: true,
  },
};

onLoadingComplete

A callback function that is invoked once the image is completely loaded and the placeholder has been removed.

<Image onLoadingComplete={callbackFn} />

onLoad

A callback function that is invoked when the image is loaded.

Note that the load event might occur before the placeholder is removed and the image is fully decoded.

<Image onLoad={callbackFn} />

onError

A callback function that is invoked if the image fails to load.

<Image onError={callbackFn} />

blurDataURL

A Data URL to be used as a placeholder image BEFORE the src image successfully loads.

Only takes effect when combined with placeholder="blur".

Must be a base64-encoded image. It will be enlarged and blurred, so a very small image (10px or less) is recommended.

Including larger images as placeholders may harm your application performance.

Scenario

SVG File Component

Import SVG File To Static URL

import MenuSVG from './Menu.svg';

<Image src={MenuSVG} alt="Menu" height={24} width={24} priority/>

Transforms SVG into React Components

Install package

npm install @svgr/webpack --save-dev
yarn add @svgr/webpack --dev

Setting the next.config.js for the svg file

// next.config.js
module.exports = {
  webpack(config) {
    config.module.rules.push({
      test: /\.svg$/,
      use: [{
        loader:'@svgr/webpack',
        options: {
          icon: true
        }
      }],
    });
    return config;
  },
}

Import the svg file as the react component

import MenuIcon from 'Menu.svg';

<MenuIcon stroke="#fff"/>

Image Domain Hosts Whitelist

You can add the specific image domain hosts to the next.config.js file as the whitelist

// next.config.js
module.exports = {
  images: {
    domains: [
      'assets.example.com',
      'i.imgur.com',
    ],
  },
}

Reference

CSS Style