Next.js 16 Image: priority Deprecated, quality Now Allowlisted

Your team ships a product page with a hero image: <Image src={photo} quality={90} priority fill />. It looked right in Next.js 15. You upgrade to 16, run a visual regression pass out of habit, and the hero image is... a little softer. Nothing crashed. No error in the terminal. No red line in CI. The quality={90} prop is still sitting right there in the JSX, doing nothing, and you'd have no way to know unless you happened to run the dev server and read a console warning that most people's eyes skip past.

That's the real story behind two changes Next.js 16 made to next/image: the quality prop is now checked against an allowlist (images.qualities, defaulting to [75]), and the priority prop is deprecated in favor of a new preload prop. Neither one is flashy enough to make a release-notes headline, and neither one throws a build error, which is exactly why they're worth a proper look: this article is written against Next.js 16.4 (verified against the framework's own next/image and next.config.js reference docs, and its source in packages/next/src/shared/lib, in October 2026), and by the end you'll know precisely what changed, why, and how to fix it on purpose instead of by accident.

By the end of this article you'll be able to:

You've used next/image in an App Router project — at minimum, you've written <Image src={...} width={...} height={...} /> and set priority on a hero image at some point. You don't need prior knowledge of the Image Optimization API internals; we build the model from the prop down to the request.

Here's the Next.js 15 component from the intro, completely ordinary code:

Upgrade to Next.js 16 with no other changes and two things happen, neither of which raises an error:

Both changes share the same shape: a prop you set still "works," in the sense that your code compiles and the page renders, while quietly doing something other than what the Next.js 15-era mental model says it does. That's the gap this article closes.

It's tempting to think of <Image quality={90} priority /> as "pass these two numbers/flags to the <img> tag." It never was that simple, and in Next.js 16 it's explicit: both props go through a validation and normalization layer that consults your next.config.js before anything is requested over the network.

The mental model: <Image>'s props aren't a direct line to the browser. They're inputs to a decision Next.js makes on your behalf, and that decision depends on config you may not have touched. Quality gets snapped to the nearest value your config allows; priority-style loading urgency gets normalized into one signal. In both cases, the component decides what actually leaves your server — your prop is a request, not a guarantee.

Two separate decisions fall out of that model, and they're the two things that changed in 16:

With no images config at all, Next.js 16's effective default is:

Key concept: every <Image quality={N}> in your app is now checked against this array. If N isn't in it, Next.js doesn't throw — it picks whichever configured value is numerically closest to N and uses that instead.

This isn't a vague "rounds to a nice number" — it's a specific, small algorithm, and you can reason about it exactly:

Try the exact same function with your own numbers in the playground below — it runs this reduction live, not a simplified stand-in.

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

If 75 is too aggressive for a photography-heavy site, widen the allowlist explicitly:

Now quality={90} on a component is requested as 90, exactly, because 90 is on the list. The fix for the regression in the intro isn't "add quality back" — it was never removed — it's "put 90 in images.qualities."

This is the part that trips people up, because there are genuinely two code paths, not one:

So "what happens if the quality isn't allowed" has two honest answers depending on which door you walked through, and both are intentional: the component degrades gracefully for real visitors; the raw endpoint stays strict so the allowlist can't be bypassed by hitting the optimizer directly.

priority on <Image> has always done two things together: it stops the image from being treated as lazy-loaded (so the browser doesn't wait to discover it near the viewport), and it has Next.js insert a <link rel="preload"> for it, so the browser's preload scanner can start fetching it before React even renders the <img> tag. That combination is exactly what you want for a Largest Contentful Paint (LCP) candidate — your hero image, the above-the-fold product photo.

Key concept: for the common case — "this is my LCP image, load it with urgency" — preload is a straight swap for priority. Both disable lazy-loading and both trigger the same preload <link> insertion; Next.js didn't change what the prop does here, it changed what it's called, specifically so the name describes the mechanism (a resource preload) instead of a vague notion of importance. You're not supposed to set both: the component throws "Only preload should be used" if a single <Image> has priority and preload together — but, like the quality-coercion warning, that check only runs while NODE_ENV !== 'production', so it surfaces in next dev, not in a next build/next start production run.

The docs are explicit that preload isn't always the right tool, even for an above-the-fold image: "In most cases, you should use loading="eager" or fetchPriority="high" instead of preload." Reach for those two directly when:

preload is a blunt, singular signal — "fetch this one early, with a <link> tag." loading/fetchPriority let the browser's own scheduler make the call across several candidates, which matters once a layout has more than one image that could end up being the LCP element on different screen sizes.

No. If 90 isn't in your images.qualities allowlist, the component silently requests the closest allowed value instead (75, with the default config). No exception, no build failure — just a different number than the one in your JSX. The console warning for this only appears in development.

Because they're different code paths. The <Image> component coerces an out-of-range quality to the closest allowed value before building the request — it never sends an invalid q. The raw optimizer endpoint validates q as a strict allowlist with no coercion, because it's a public HTTP surface that has to reject bad input rather than guess what you meant.

No, it's deprecated, not removed. It still compiles and still behaves the same as preload for the eager-load-plus-preload-link use case. The Version History table in the official <Image> reference records it as deprecated starting in v16.0.0.

Not urgently — there's no runtime warning pushing you to, and the behavior hasn't changed. Treat it like any other mechanical rename: do it the next time you're already touching a file, or as a dedicated sweep during a major-version upgrade, rather than a hotfix.

Only partly. The dev-only console warning for an out-of-allowlist quality fires regardless of which loader you use. But the actual snap-to-closest-value coercion (findClosestQuality) is implemented inside Next.js's own default loader, not in a shared layer every loader passes through — a custom loader function or images.loaderFile receives the raw quality prop exactly as written and is responsible for applying (or ignoring) images.qualities itself. It also isn't going through the /_next/image endpoint in the typical case, so the strict-400 behavior doesn't apply there either.

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

You upgrade, the build succeeds, the page looks almost right — and that gap between "compiles" and "renders exactly as specified" is where both of these changes live. Now that you've seen the allowlist and the rename from the inside, a soft hero image or a silently-working priority prop stops being a mystery and starts being a one-line fix in next.config.js or a safe find-and-replace.

If you've been caught by either of these since upgrading to Next.js 16, or found a case the allowlist handles differently than described here, say so in the comments — these are the two next/image changes with the fewest search results and the most "wait, why did my image get softer" GitHub issues.

This episode builds on two earlier ones in this series: Next.js Cache Components Explained covers the broader caching model next/image sits alongside, and Next.js Route Handlers: GET Stopped Caching in 15 is the same "quiet default change with no error message" pattern applied to Route Handlers instead of <Image>.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected: