Image (Legacy)

Core Idea

next/legacy/image is the pre-v13 Image component, kept only for backward compatibility. Deprecated since v16.0.0; use next/image instead.

Key Concepts

• next/legacy/image: renamed from the old next/image in v13; wraps <img> in a <span> and uses layout/objectFit/objectPosition props instead of style/className.
• layout: one of intrinsic (default), fixed, responsive, fill — controls resize behavior and generated srcSet/sizes.
• loader: function ({ src, width, quality }) => url to resolve image URLs, overrides the next.config.js loader.
• unoptimized: serves the source as-is, skipping quality/size/format transforms.
• remotePatterns / domains: next.config.js allowlist for external image hosts; domains is deprecated in favor of remotePatterns.

Code Examples

import Image from 'next/legacy/image'

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

const MyImage = (props) => (
  <Image loader={myLoader} src="me.png" alt="Picture of the author" width={500} height={500} />
)

• O que demonstra: custom loader prop resolving the final image URL.

Reference Tables

layout	Behavior	srcSet	sizes
intrinsic (default)	scale down to fit container, up to image size	1x,2x	N/A
fixed	exact width/height	1x,2x	N/A
responsive	scale to fit container width	width-based	100vw
fill	grow to fill parent (needs position: relative on parent)	width-based	100vw

Anti-patterns

• New projects using next/legacy/image: deprecated, will be removed; use next/image.
• SVG without unoptimized/dangerouslyAllowSVG: blocked by default for security.

Key Takeaways

1. This is a migration/back-compat API only, not for new code.
2. layout="fill" requires the parent to have position: relative.
3. External images always require remotePatterns (or the deprecated domains) configuration.
4. unoptimized bypasses the whole optimization pipeline, useful for tiny/animated/vector images.

Connects To

• Image (current): next/image is the direct, non-legacy replacement.
• next.config.js images options: deviceSizes, imageSizes, formats, minimumCacheTTL all apply to the legacy loader too.