NextJS Image Missing Width Property

Problem

When using the Next.js Image component in development mode (npm run dev), you may encounter the error: "missing required 'width' property". This occurs even when external CSS styles define dimensions. The error trace shows the component fails without explicit width and height props:

Error: Image with src "image-url" is missing required "width" property.

Attempting to style the image with an external CSS file doesn't resolve the issue. The only temporary fix is manually adding inline width and height attributes to every Image instance.

Solution

Use fill with a container element

The correct approach for responsive images without explicit dimensions is using the fill prop with a positioned parent container:

<div className="relative h-64">
  <Image
    src="/next.svg"
    alt="Next.js Logo"
    fill
    className="object-contain"
  />
</div>

Key requirements for this approach:

1. Wrap the Image in a container with position: relative
2. The container must have explicit dimensions (e.g., height/width via CSS classes)
3. Use fill prop to make the image expand to container dimensions

Alternative: Specify dimensions directly

For fixed-size images, explicitly provide width and height:

<Image
  src="/next.svg"
  alt="Next.js Logo"
  width={300}
  height={200}
/>

---

Why This Happens

• The Next.js Image component requires either explicit dimensions (width/height props) or the fill property to prevent layout shifts and enable optimization
• External CSS dimensions aren't detected during server-side rendering
• Using fill without a position: relative container causes rendering issues since images default to position: absolute

Critical Considerations

1. Container constraints

When using fill, the parent container controls the image size:

<div className="grid grid-cols-2">
  <div>Content defining container height</div>
  <div className="relative">
    <Image
      src="/hero.jpg"
      alt="Hero image"
      fill
    />
  </div>
</div>

WARNING

If your image doesn't appear with fill:

• Verify the parent has position: relative
• Confirm the container has dimensions (e.g., set height in CSS)
• Check the container isn't collapsed (height > 0px)

2. Height conflicts with Tailwind

Using fill with height utilities requires special handling:

{/* Correct: Explicit height */}
<div className="relative h-[300px]">
  <Image 
    src="/banner.png" 
    alt="Banner" 
    fill 
  />
</div>

{/* Problematic: Height conflicts */}
<Image
  src="/banner.png"
  alt="Banner"
  fill
  className="h-full" // Won't work
/>

3. Image styling techniques

Control aspect ratio and cropping with CSS:

{/* Maintain aspect ratio */}
<div className="relative aspect-video">
  <Image
    src="/landscape.jpg"
    alt="Scenic view"
    fill
    className="object-cover"
  />
</div>

TIP

Use these object-fit values:

• contain: Full image visible with letterboxing
• cover: Fill container (crops edges)
• fill: Stretch to container (distorts!)

Advanced Implementation

Dynamic images

For remote images or dynamically-loaded assets, specify sizes for responsive breakpoints:

<Image
  src={dynamicSrc}
  alt="User content"
  fill
  sizes="(max-width: 768px) 100vw, 50vw"
  className="bg-gray-200 rounded-lg"
/>

Mocking in tests

When encountering errors in test environments (Jest/RTL), provide valid mock sources:

// Jest setup
import mockImage from '@/assets/test-image.png';

jest.mock('next/image', () => ({
  __esModule: true,
  default: (props) => <img {...props} src={mockImage.src} />,
}));

Conclusion

Resolve missing width errors by either:

1. Providing explicit width/height props, or
2. Using fill with a relatively-positioned container

Always ensure the parent container has defined dimensions when using fill. For responsive images, combine fill with object-fit and sizes for perfect responsive behavior.