How to Use the Next.js Image Component with Unknown Width and Height: 3 Methods

Use the fill prop to stretch the image to a parent container’s dimensions, supply intrinsic dimensions with responsive CSS to preserve aspect ratio, or set unoptimized to bypass the optimizer entirely.

The Next.js Image component optimizes images at build time and runtime to prevent layout shift and improve Core Web Vitals. When working with dynamic content or third-party sources where exact pixel dimensions are not known beforehand, the vercel/next.js repository provides three distinct patterns to satisfy the component’s sizing requirements without sacrificing performance.

Why the Image Component Requires Dimensions

Next.js pre-computes image placeholders and srcset entries during static-site generation (SSG) and server-side rendering (SSR). The optimizer in packages/next/src/server/image-optimizer.ts uses width and height values to calculate optimal output sizes and generate responsive variants. Additionally, explicit dimensions allow the browser to reserve the correct amount of space before the image loads, preventing Cumulative Layout Shift (CLS).

According to the source code in packages/next/src/client/image-component.tsx, the component throws a runtime error if neither width/height props nor the fill prop is provided. When you cannot provide concrete pixel values, the following strategies satisfy this validation while maintaining the component’s performance benefits.

Method 1: Fill a Parent Container with the fill Prop

The fill prop (formerly layout="fill") instructs the image to stretch to the dimensions of its nearest positioned parent element. This pattern is ideal when the image must match a container whose size is controlled by CSS, such as a responsive grid cell or hero banner.

The parent element must have position: relative (or absolute/fixed) to establish a positioning context. The image then uses absolute positioning to cover the container, and you control the final appearance with object-fit.

// components/HeroImage.tsx
import Image from 'next/image';
import styles from './HeroImage.module.css';

export default function HeroImage({ src, alt }: { src: string; alt: string }) {
  return (
    <div className={styles.container}>
      <Image
        src={src}
        alt={alt}
        fill
        priority
        sizes="100vw"
        style={{ objectFit: 'cover' }}
      />
    </div>
  );
}

/* components/HeroImage.module.css */
.container {
  position: relative;  /* Required for fill to work */
  width: 100%;
  height: 400px;       /* Or any responsive height value */
  overflow: hidden;    /* Optional: clips overflow */
}

As implemented in packages/next/src/client/image-component.tsx, the fill prop bypasses the requirement for explicit width and height props because the rendered size is derived entirely from the parent’s layout box.

Method 2: Preserve Aspect Ratio with Intrinsic Dimensions

When you know the image’s aspect ratio but not the final rendered pixel size, provide the intrinsic width and height as props to satisfy the optimizer, then use CSS to make the image responsive. The props tell Next.js the aspect ratio for generating the srcset, while style={{ width: '100%', height: 'auto' }} allows the image to scale fluidly within its container.

// components/ResponsiveImage.tsx
import Image from 'next/image';

export default function ResponsiveImage({
  src,
  alt,
  intrinsicWidth,
  intrinsicHeight,
}: {
  src: string;
  alt: string;
  intrinsicWidth: number;
  intrinsicHeight: number;
}) {
  return (
    <Image
      src={src}
      alt={alt}
      width={intrinsicWidth}    /* Used for aspect ratio calculation */
      height={intrinsicHeight}
      style={{
        width: '100%',
        height: 'auto',
      }}
      sizes="(max-width: 768px) 100vw, 50vw"
    />
  );
}

Even though the rendered dimensions are unknown at compile time, this approach provides the optimizer in packages/next/src/server/image-optimizer.ts with the necessary aspect ratio to generate appropriately sized variants at runtime.

Method 3: Bypass the Optimizer with unoptimized

For images served from external CDNs or third-party services that handle their own optimization, use the unoptimized prop combined with a custom loader. This disables Next.js image optimization entirely, causing the component to behave like a standard HTML img element and removing the requirement for meaningful dimension values.

// components/ExternalImage.tsx
import Image from 'next/image';

const externalLoader = ({ src }: { src: string }) => src;

export default function ExternalImage({ src, alt }: { src: string; alt: string }) {
  return (
    <Image
      src={src}
      alt={alt}
      loader={externalLoader}
      unoptimized
      width={1}      /* Syntactically required but ignored */
      height={1}
    />
  );
}

The configuration parsing in packages/next/src/shared/lib/image-config.ts processes the unoptimized flag, while packages/next/src/client/image-component.tsx skips the dimension validation when optimization is disabled.

Summary

• Use the fill prop when the image must match a parent container’s CSS-defined dimensions. Ensure the parent has position: relative.
• Provide intrinsic dimensions with responsive CSS when you know the aspect ratio but not the final rendered size. Set width and height props for the optimizer, then use style or CSS for fluid sizing.
• Set unoptimized={true} for external image services that bypass the Next.js optimizer. This removes dimension constraints but sacrifices built-in optimization features.

Frequently Asked Questions

What happens if I don't provide width and height to the Next.js Image component?

The component throws a runtime error during development. The validation logic in packages/next/src/client/image-component.tsx requires either both width and height props, or the fill prop, to prevent layout shift and enable the optimizer to function.

Can I use CSS width and height instead of props?

You must still provide the width and height props (or fill) to satisfy the component’s TypeScript definitions and runtime validation. However, you can override the rendered size with CSS. When using the fill prop, CSS exclusively controls the dimensions via the parent container. When using intrinsic dimensions, CSS can scale the image responsively while the props preserve the aspect ratio.

Does the fill prop affect image quality or loading performance?

The fill prop itself does not degrade quality, but you should always provide the sizes prop to help the browser select the optimal image resolution from the srcset. Without accurate sizes, the browser may download an unnecessarily large image file, impacting performance. The priority prop should be added for above-the-fold images to preload them.

When should I use unoptimized instead of the default optimizer?

Use unoptimized when integrating with external image services like Cloudinary, Imgix, or CMS-hosted assets that already provide dynamic resizing and format optimization. Setting unoptimized prevents double-processing and avoids constraints on dimension props, though you lose Next.js’s automatic WebP/AVIF conversion and blur placeholder features.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}