How to Set the Next.js Image Component to 100% Height: A Complete Guide

Use layout="fill" on the Next.js Image component with a parent container that has position: relative and an explicit height.

The Next.js Image component from the vercel/next.js repository provides automatic optimization and responsive layouts, but achieving full container height requires understanding how the layout prop interacts with CSS. To set the Next.js image component to 100% height, you must combine the fill layout mode with a properly sized parent container that establishes a positioning context.

Understanding the Next.js Image Component Layout System

According to the source code in packages/next/src/client/image-component.tsx, the Next.js Image component renders a wrapper <span> element with position: relative when using layout="fill". The actual <img> element receives absolute positioning and stretches to fill both the width and height of this wrapper.

The wrapper inherits its dimensions from the parent container. Therefore, the image only achieves 100% height when the parent has an explicit height defined (such as h-screen, h-96, or a fixed pixel value). Without this explicit height, the relative wrapper collapses to zero height, and the absolute image disappears.

Setting Next.js Image to 100% Height: Step-by-Step Implementation

Step 1: Create a Relative Parent Container with Explicit Height

The parent element must establish both a positioning context and a concrete height value. In packages/next/src/client/image-component.tsx, the component checks for position: relative on the parent to ensure proper absolute positioning calculations.

// Parent container with explicit height
<div className="relative h-screen w-full">
  {/* Image will fill this container */}
</div>

Step 2: Apply layout='fill' and objectFit Properties

Set the layout prop to "fill" and choose an appropriate objectFit value. The objectFit property maps directly to the CSS object-fit property, controlling how the image content scales within the 100% height container.

<Image
  src="/photos/example.jpg"
  alt="Description"
  layout="fill"
  objectFit="cover"
/>

Practical Code Examples

Tailwind CSS Implementation

This example uses Tailwind utility classes to create a full-height hero section. The implementation references the layout behavior defined in packages/next/src/client/image-component.tsx.

import Image from 'next/image'

export default function HeroSection() {
  return (
    <div className="relative h-96 w-full">
      <Image
        src="/photos/mountain.jpg"
        alt="Mountain landscape"
        layout="fill"
        objectFit="cover"
        priority
      />
      <div className="absolute inset-0 flex items-center justify-center">
        <h1 className="text-4xl font-bold text-white">Explore the World</h1>
      </div>
    </div>
  )
}

Flexbox Layout with Full Viewport Height

When using flexbox layouts, the image container can use flex-1 to occupy remaining space. This pattern appears in various Next.js examples within the repository.

import Image from 'next/image'

export default function SplitLayout() {
  return (
    <section className="flex h-screen">
      <article className="flex-1 p-8">
        <h1 className="text-4xl font-bold">Content Side</h1>
        <p className="mt-4">Text content goes here.</p>
      </article>
      
      <div className="relative flex-1">
        <Image
          src="/photos/ocean.jpg"
          alt="Ocean view"
          layout="fill"
          objectFit="cover"
        />
      </div>
    </section>
  )
}

CSS Modules Approach

For projects using CSS Modules, define explicit height in your stylesheet while maintaining the layout="fill" configuration.

/* components/FullHeightImage.module.css */
.imageContainer {
  position: relative;
  height: 60vh;
  width: 100%;
}

.overlay {
  position: absolute;
  inset: 0;
  background: rgba(0, 0, 0, 0.3);
  z-index: 10;
}

import Image from 'next/image'
import styles from './FullHeightImage.module.css'

export default function StyledImage() {
  return (
    <div className={styles.imageContainer}>
      <Image
        src="/photos/forest.jpg"
        alt="Forest path"
        layout="fill"
        objectFit="cover"
      />
      <div className={styles.overlay} />
    </div>
  )
}

Key Source Files and Implementation Details

The behavior described above is implemented in the following files within the vercel/next.js repository:

• packages/next/src/client/image-component.tsx: Contains the main React component implementation, including the layout="fill" logic that creates a relative wrapper and absolutely positioned image element.
• packages/next/src/shared/lib/image-config.ts: Defines the configuration types and default values for image optimization settings used by the component.
• packages/next/src/shared/lib/image-loader.ts: Implements the default image loader that generates optimized URLs based on the layout and sizing props.
• docs/02-pages/04-api-reference/01-components/image.mdx: Official documentation covering the layout and objectFit properties.

Summary

• Use layout="fill" to make the Next.js Image component stretch to fill both width and height of its parent container.
• Set position: relative on the parent element to establish a positioning context for the absolutely positioned image.
• Define explicit height on the parent container (using Tailwind classes, CSS Modules, or inline styles) so the image has a concrete height value to fill.
• Choose objectFit appropriately (cover, contain, or fill) to control how the image content scales within the 100% height container.
• Reference packages/next/src/client/image-component.tsx for the underlying implementation details of the layout system.

Frequently Asked Questions

Why does my Next.js Image component collapse to zero height when using layout="fill"?

The image collapses because the parent container lacks an explicit height definition. According to the implementation in packages/next/src/client/image-component.tsx, the layout="fill" mode positions the image absolutely within a relative wrapper. If the parent has no height (or height: auto), the wrapper collapses to zero pixels. Always set a concrete height on the parent element using CSS classes like h-96, h-screen, or fixed pixel values.

Can I use layout="fill" with responsive height containers like flex-grow?

Yes, layout="fill" works perfectly with flexbox layouts. When a parent container uses display: flex with a defined height (such as h-screen), child elements can use flex-1 or flex-grow to distribute space. The image wrapper will inherit the calculated height from the flex container, allowing the image to fill 100% of the allocated space. This pattern is commonly used in split-screen layouts where one side contains text and the other contains a full-height image.

What is the difference between objectFit="cover" and objectFit="contain" when filling height?

objectFit="cover" scales the image to fill the entire height (and width) of the container while maintaining aspect ratio, cropping any excess parts of the image. This is ideal for background images or hero sections where you want the image to fill the space completely. Conversely, objectFit="contain" scales the image to fit within the container's height and width while maintaining aspect ratio, ensuring the entire image is visible. This may result in letterboxing (empty space) if the aspect ratios don't match. Both values map directly to the CSS object-fit property applied to the image element in packages/next/src/client/image-component.tsx.

Does using layout="fill" affect image optimization and lazy loading?

No, layout="fill" maintains all Next.js image optimization features. The component still automatically generates responsive srcsets, supports lazy loading (unless priority is set), and serves optimized formats like WebP when supported. The layout prop only affects the CSS positioning strategy used to render the image. In packages/next/src/shared/lib/image-loader.ts, the loader continues to calculate optimal dimensions based on the device sizes defined in your configuration, regardless of whether you use fill, responsive, or fixed layouts.

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