Images with next/image

The Image component from next/image replaces the ordinary img tag. It resizes the image for the screen, converts it to a light format such as WebP, loads it only when it gets close to the visible area and reserves space so the page does not "jump" while loading.

An image from public

Put a cover.jpg file into the public/ folder. Files from there are available from the site root: /cover.jpg.

// app/about/page.tsx
import Image from 'next/image';
 
export default function AboutPage() {
  return (
    <main>
      <h1>About the blog</h1>
      <Image src="/cover.jpg" alt="Anna's workspace" width={800} height={400} />
    </main>
  );
}

The width and height props are required: from them the browser knows the proportions in advance. Open /about and look at the image address in the developer tools — it starts with /_next/image, which is the processed version.

Importing the file

An image can be imported as a module. Then Next.js finds out the size itself:

// app/about/page.tsx (fragment)
import Image from 'next/image';
import cover from './cover.jpg';
 
<Image src={cover} alt="Anna's workspace" placeholder="blur" />;

Here cover.jpg sits next to the page. placeholder="blur" shows a blurred copy while the original loads.

Images from another site

External addresses require allowing the domain in next.config.ts:

// next.config.ts
import type { NextConfig } from 'next';
 
const nextConfig: NextConfig = {
  images: {
    remotePatterns: [{ protocol: 'https', hostname: 'images.example.com' }],
  },
};
 
export default nextConfig;

After restarting npm run dev you can write src="https://images.example.com/post-1.jpg" together with width and height.

Filling a box

When the size is not known in advance, such as a full-width post cover, use fill. The image stretches over its parent, which needs position: relative and a height:

// app/posts/[slug]/page.tsx (fragment)
<div style={{ position: 'relative', height: 300 }}>
  <Image src="/cover.jpg" alt="Cover" fill sizes="100vw" style={{ objectFit: 'cover' }} />
</div>

sizes tells the browser how wide the image will be on screen so it can pick a suitable variant.

The main image of the screen

For a large image at the very top of the page, add the preload prop: Next.js starts loading it right away, before the page is parsed. In Next.js 16 it replaced the deprecated priority prop you will see in older examples. Give preload to only one image per page.

Common mistake

Using an external address without configuring remotePatterns. The page fails with "hostname is not configured under images in your next.config". Add the domain to next.config.ts and restart the development server — the settings file is read only on start.