Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

next/image ignores layout, objectFit and layout="fill"

ErrorNext.JS Image `layout='fill'` is broken

Short answer

Since Next.js 13 the next/image component no longer accepts layout, objectFit or objectPosition. Use the boolean fill prop, give the parent element position relative, and set object-fit through style or a class. If you need the old behaviour unchanged, import the legacy component instead.

  • Applies to Next.js 15, Next.js 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Search the code for the old props and for the import path. They tell you which of the causes below applies.

    grep -rn "layout=\|objectFit=\|objectPosition=\|next/legacy/image" app components pages src 2>/dev/null
  2. 2Match what you see, then jump to its fix

    1. 1The image is the wrong size or does not cover its box, and the JSX still has layout="fill" objectFit="cover".The old layout and objectFit props are still on the componentFix
    2. 2With fill the image overflows the page, covers other content or has zero height.The parent element is not positionedFix
    3. 3Many files use layout="responsive", "fixed" or "intrinsic" and a rewrite is not possible right now.A project still depends on the pre-13 componentFix

What does the error look like?

  • Next.JS Image `layout='fill'` is broken
  • layout, objectFit, objectPosition, lazyBoundary, lazyRoot props removed

Cause 1 of 3

The old layout and objectFit props are still on the component

1Check

The Next.js 13 release removed the layout, objectFit, objectPosition, lazyBoundary and lazyRoot props from next/image.

grep -rn "layout=" app components pages 2>/dev/null

2Fix

Replace layout="fill" with the fill prop and move objectFit into style. A component that uses fill must also have alt.

// before
<Image src="/hero.jpg" layout="fill" objectFit="cover" alt="" />

// after
<Image src="/hero.jpg" fill style={{ objectFit: 'cover' }} alt="Hero" />

3Verify

Reload the page and check that the image fills its box and is cropped, not stretched.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 3

The parent element is not positioned

1Check

An image with fill is position absolute. It sizes against the nearest positioned ancestor, so that ancestor needs position relative, fixed or absolute. The parent also needs a size.

grep -rn -B2 "fill" app components | grep -n "position\|relative"

2Fix

Wrap the image in an element with position relative and a width and height (or an aspect ratio).

<div style={{ position: 'relative', width: '400px', height: '300px' }}>
  <Image src="/hero.jpg" alt="Hero" fill style={{ objectFit: 'cover' }} />
</div>

3Verify

Inspect the page: the img element stays inside the wrapper box.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

A project still depends on the pre-13 component

1Check

In v13.0.0 the old component was renamed to next/legacy/image, and a codemod renames imports.

grep -rln "from 'next/image'" app components pages 2>/dev/null | head

2Fix

Import the legacy component where you still need the old props, and plan the move to fill, or to width and height, file by file.

import Image from 'next/legacy/image'

3Verify

The page renders as it did before the upgrade.

npm run build

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Give every fill image a positioned wrapper with a defined size, in the same commit.
  • Pass the sizes prop with fill so the browser does not download an image sized for the whole viewport.
  • Set width and height on images whose size is known; use fill only when it is not.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.