DEV Community: Mohamed Gado

React error #418: fixing a matchMedia hydration mismatch with useSyncExternalStore

Mohamed Gado — Wed, 11 Nov 2026 00:03:29 +0000

Minified React error #418 means the HTML the server rendered did not match what the client rendered on its first pass. On my Next.js site the cause was a useMediaQuery hook that read window.matchMedia(query).matches inside a useState initializer. The server returned false, a desktop browser returned true, and React threw away the server HTML. Rewriting the hook on useSyncExternalStore with a getServerSnapshot of false made the first client render match the server by construction.

What does minified React error #418 mean?

React 19 reports it as "Hydration failed because the server rendered HTML didn't match the client." During hydration React walks the server HTML and the first client render side by side. If one has a node the other lacks, React cannot reuse the markup. It discards the server tree and renders the whole app again on the client.

In production the message is minified, so all you get is #418 and a link. It names no component and no node. On my site it fired on every production page load, and nothing looked broken, because the client re-render produced a correct page. The cost was invisible: the server HTML was thrown away, and every visitor paid for a full client render. I think this is what my earlier performance audit recorded as "mobile lab bound by react-dom hydration", but I have no before and after measurement to prove that link.

Why does reading matchMedia in useState cause a hydration mismatch?

The server has no window. A hook that wants to run on both sides has to pick a value for the server, and the natural choice is false. The mistake is reading the browser value during the first client render.

This is the shape of my broken hook. It is simplified, not the exact file I had:

import { useEffect, useState } from 'react'

// Broken: the first client render reads the browser, the server cannot.
export function useMediaQuery(query: string): boolean {
  const [matches, setMatches] = useState(() =>
    typeof window === 'undefined' ? false : window.matchMedia(query).matches
  )

  useEffect(() => {
    const mql = window.matchMedia(query)
    const onChange = () => setMatches(mql.matches)
    mql.addEventListener('change', onChange)
    return () => mql.removeEventListener('change', onChange)
  }, [query])

  return matches
}

On the server the initializer returns false. In a desktop browser the same initializer runs during the first client render and returns true. Hydration compares the two trees at that moment, so the value is already different before any effect runs.

The caller made it visible. My spotlight component draws a cursor-following overlay only when the device has a fine pointer:

const hasFinePointer = useMediaQuery('(pointer: fine)')

// ...
{hasFinePointer && (
  <div ref={overlay} className="pointer-events-none fixed inset-0 z-30 ..." />
)}

The server rendered no overlay. The desktop client rendered one extra child, so every sibling after it shifted position. That is enough for #418.

How do I find which component mismatches?

Production will not tell you. Run pnpm dev (or your package manager's dev command) and load the page. The development build of React prints the full, non-minified error, including a component stack with + and - lines that mark the exact mismatched node. The + side is what the client rendered and the - side is what the server sent. For my bug that diff pointed at the spotlight overlay div.

Two things to check once you have the component:

Does it read window, document, localStorage, matchMedia or Date.now() while rendering, or in a useState initializer?
Does it branch the JSX on that value?

If both are yes, you have found it. Other common causes of #418 are invalid HTML nesting and browser extensions that modify the DOM, but those did not apply here.

A second clue was sitting in my own code. A mounted guard already existed in a command palette trigger, with a comment explaining that the media query mismatched. The spotlight had no such guard. A per-caller workaround for a hook-level bug is the signal to fix the hook.

How do I fix it with useSyncExternalStore?

useSyncExternalStore takes three arguments: subscribe, getSnapshot and getServerSnapshot. From the React docs, getServerSnapshot is used during server rendering and during hydration on the client. That is the property that matters here. React does not call your client getSnapshot for the hydrating render, so the first client render sees the same false the server saw. Right after hydration finishes, React reads the real snapshot and re-renders if it differs. The docs describe this behaviour, and I did not trace it through React's source.

This is the hook as it is now in my repo:

import { useCallback, useMemo, useSyncExternalStore } from 'react'

export function useMediaQuery(query: string): boolean {
  // One MediaQueryList per query, reused by both subscribe and getSnapshot.
  const mql = useMemo(
    () => (typeof window === 'undefined' ? null : window.matchMedia(query)),
    [query]
  )

  const subscribe = useCallback(
    (onStoreChange: () => void) => {
      mql?.addEventListener('change', onStoreChange)
      return () => mql?.removeEventListener('change', onStoreChange)
    },
    [mql]
  )

  return useSyncExternalStore(
    subscribe,
    () => mql?.matches ?? false,
    () => false
  )
}

Three details in it are worth copying:

The MediaQueryList is created once per query in useMemo. getSnapshot runs on every render, so calling matchMedia inside it would repeat work for no reason.
subscribe is wrapped in useCallback keyed on the list. A new function identity each render would make React unsubscribe and resubscribe every time.
The server snapshot is a constant false. That is the contract for callers: the first paint always has false, and the real value arrives in the commit right after.

Do I still need a mounted guard?

No. Once the hook returns false on the first client render, a mounted state flag adds nothing. I deleted the guard in the palette trigger. That component now hides itself on desktop with the Tailwind class sm:hidden, which is CSS and needs no JavaScript value at all.

This points at the cheaper option for many cases. If a media query only changes layout or visibility, use CSS. Keep useMediaQuery for the cases where JavaScript has to act on the result, such as attaching a mouse handler, as my spotlight does.

The trade-off is a one-frame flash. With a false server snapshot, a desktop user gets the touch layout first and the desktop layout after hydration. For my overlay that is invisible, since it is a faint gradient. For a layout that changes the page structure, pick a server default that suits your most common visitor, or use CSS.

How do I confirm the fix worked?

In production, the console on a fresh page load no longer shows #418; the only errors left there come from browser extensions. If it ever comes back, pnpm dev is where to look, since it prints the full hydration warning with its component stack.

One trap while checking: counting JSON-LD tags with a bare grep for application/ld+json double-counts, because the RSC payload embeds the component tree as an escaped string. Count real tags with grep -o '<script type="application/ld+json"' instead, or document.querySelectorAll in the browser.

The rule I took from it: never read window, matchMedia or localStorage in a useState initializer in a component that renders on the server. Use useSyncExternalStore with a server snapshot, or use CSS.

The site this came from is described in the portfolio case study. Another rendering bug from the same site, a 200 status on unknown slugs, is covered in Next.js soft 404: why notFound() returned 200 behind loading.tsx.

Next.js soft 404: why notFound() returned 200 behind loading.tsx

Mohamed Gado — Wed, 11 Nov 2026 00:03:03 +0000

On my Next.js 16 site, a URL like /projects/nope returned HTTP 200 and carried two robots tags: index, follow and noindex. The route has a loading.tsx, which starts streaming before notFound() runs, so the status code was already sent. Adding export const dynamicParams = false to the page makes an unknown slug a real 404 before any rendering starts.

Why does notFound() return 200 in the Next.js App Router?

I found this during a Search Console pass. Unknown project slugs were not 404s. The Next.js docs describe the mechanism in the loading.js reference: streaming page responses begin with a 200 status code, and the initial response headers fix the status for the rest of the response. Next.js can still stream notFound() after that, so the browser shows your not-found UI, but the status line stays 200.

The docs also say when the stream starts. The response body begins streaming when a Suspense fallback renders, and they give loading.tsx as the example, or when a Server Component suspends under a <Suspense> boundary. Calling notFound() before that point preserves the 404. After it, the status cannot change.

A loading.tsx file is a Suspense fallback wrapped around the segment's page. For a dynamic route, that means the fallback can be sent before your page code has a chance to look up the slug and decide it does not exist.

What does a soft 404 look like for Google?

A soft 404 is a page that tells the user "not found" but tells the crawler 200 OK. Next.js softens the damage: the docs say it injects <meta name="robots" content="noindex" /> into a streamed 404, so search engines are told to keep the URL out of the index even though the status is 200. They also note that some crawlers may label these responses as soft 404s.

On my site the result was messier. The root layout already set index, follow, and the streamed not-found added noindex. The page carried both tags with a 200 status. I did not want to find out which one a crawler would trust, and I did not want Search Console reporting junk URLs as soft 404s.

How do I reproduce it?

Here is the shape of the broken segment. The names are simplified from my project route:

// app/projects/[slug]/page.tsx
import { notFound } from 'next/navigation'

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const project = findProject(slug)
  if (!project) notFound() // too late: loading.tsx already streamed a 200

  return <ProjectView project={project} />
}

// app/projects/[slug]/loading.tsx
export default function Loading() {
  return <ProjectSkeleton />
}

Check the status with curl:

curl -s -o /dev/null -w "%{http_code}\n" https://example.com/projects/nope

You want 404. In my case it printed 200. To see the duplicate robots tags, fetch the body:

curl -s https://example.com/projects/nope | grep -o '<meta name="robots"[^>]*>'

What fixed it: dynamicParams = false

Every project on my site is already prerendered through generateStaticParams. The fix was one line in the page file, with a comment I left for my future self:

// app/projects/[slug]/page.tsx

// Every project is prerendered below, so an unknown slug is a 404 at routing.
// Left on, it rendered on demand and hit notFound() after [slug]/loading.tsx
// had already streamed a 200: a soft 404 carrying both index and noindex.
export const dynamicParams = false

export async function generateStaticParams() {
  const slugs = await listProjectSlugs()
  return slugs.map((slug) => ({ slug }))
}

The reference for dynamicParams says that with the default of true, segments not returned by generateStaticParams are generated at request time, and with false they return a 404. An unknown slug never reaches your page component, so loading.tsx never streams for it, and the response is a real 404 from routing.

After the change, an unknown slug is a real 404 from routing. The curl check against /projects/nope on my live site now prints 404.

I left loading.tsx in place. At one point I suspected both loading files of bloating the DOM and removed them to test it. The DOM went from 951 to 949 nodes, so they went back. The soft 404 was their only real cost, and dynamicParams fixed that without touching them.

When is dynamicParams = false the wrong fix?

It fits when you know every valid slug at build time. If your slugs come from a database that changes after deploy, false would 404 a page that was added after the build, until you rebuild or revalidate.

The docs also list a restriction: dynamicParams is not available when Cache Components is enabled. I did not test that configuration, so check your own setup if you use it.

For a route that has to render on demand, the docs give a different answer. Run the check before the body streams. For a 404, you can check the slug in Proxy, then rewrite to a not-found route or return a 404 response, and the docs say to keep Proxy checks fast and avoid fetching full content there. I use a proxy for a related case on this site: malformed UTF-8 in a URL, such as /projects/%C0%AF, used to be a 500 on decode. proxy.ts, which is the Next 16 name for middleware, now returns a 404 for those. Its matcher only runs on dynamic segments that contain a %, so no other request pays for it.

The other option is to call notFound() before any await on a slow path and before any <Suspense> boundary. The streaming guide recommends exactly that placement to get a real status code.

How do I check every dynamic route for this?

The rule I wrote down after this: any dynamic route with a loading.tsx must 404 without rendering. That means dynamicParams = false, or a proxy check.

To audit a site:

List the routes with a dynamic segment and a loading.tsx next to them.
Request a nonsense slug on each one from a production build and read the status code with curl.
Anything that prints 200 with a not-found page is a soft 404.
Fix it with dynamicParams = false if the slug set is known at build time, or with a proxy check if it is not.

The site this came from is documented in the portfolio case study, and the project pages that carry the fix are listed on /projects.

Next.js metadata openGraph not inherited: why my subpages lost og:site_name

Mohamed Gado — Wed, 11 Nov 2026 00:02:39 +0000

If a page in the Next.js App Router sets its own openGraph, the openGraph object from your layout is gone for that page. Next.js merges metadata shallowly, so og:site_name, og:locale and any other field you only set in the layout disappear. The fix I use is one helper that builds the full openGraph and twitter objects for every subpage, plus a build check that fails when a tag is missing.

I found this on my own site, mohamedgado.com. /now, /projects and all 55 case studies were shipping without og:site_name, og:locale, twitter:site and twitter:creator. The root layout set all four. Nothing in the browser looked wrong, and nothing errored.

Does Next.js merge openGraph metadata from the layout?

No, not field by field. The Next.js 16 docs for generateMetadata say that metadata objects exported from several segments of one route are shallowly merged, and that duplicate keys are replaced by the segment closest to the page. They also say it directly for nested fields: openGraph defined in an earlier segment is overwritten by the last segment that defines it.

The docs give the example. The layout sets openGraph.title and openGraph.description. The blog page sets only openGraph.title. The output has the page's og:title and no og:description, because the page's whole openGraph object replaced the layout's.

The same page does inherit when it does not set openGraph at all. A subpage with only a title still gets every Open Graph tag from the layout. The trouble starts the moment a page adds openGraph to change one field, such as the title or the image. That is the normal thing to do on a case study or a blog post, so it hits most real sites.

What did the broken setup look like?

My root layout carried the full set:

// app/layout.tsx
export const metadata: Metadata = {
  openGraph: {
    locale: siteConfig.openGraph.locale,
    siteName: siteConfig.name,
    url: siteConfig.links.websiteUrl,
    type: 'website',
    title: `${siteConfig.name} — ${siteConfig.tagline}`,
    description: siteConfig.description,
  },
  twitter: {
    card: 'summary_large_image',
    creator: siteConfig.twitterTag,
    site: siteConfig.twitterTag,
  },
}

A subpage then set what it needed, which looks harmless. This is a simplified version of what the case-study page did before the helper:

// app/projects/[slug]/page.tsx (before)
return {
  title: project.title,
  openGraph: {
    title: `${project.title} | Mohamed Gado`,
    description,
    url: `/projects/${slug}`,
    images: [ogImage],
  },
  twitter: {
    card: 'summary_large_image',
    title: `${project.title} | Mohamed Gado`,
    description,
  },
}

This page's openGraph has no siteName and no locale, so neither tag is rendered. Its twitter has no site or creator, so those are gone too. The layout's values were replaced, not combined.

How do I check the rendered tags?

Read the HTML the server sends, not the code. A dev tool that shows the metadata object tells you what you wrote, and the question is what crawlers receive. I curl the page and grep for the tag:

curl -s https://www.mohamedgado.com/projects/masareef | grep -o '<meta[^>]*og:site_name[^>]*>'
curl -s https://www.mohamedgado.com/projects/masareef | grep -oE '<meta[^>]*(og:locale|twitter:site|twitter:creator)[^>]*>'

An empty result means the tag is missing. I ran this against production before writing any code, because I wanted to know the gap was real on every subpage and not something I had inferred from reading the merge docs. It was.

What is the fix for Next.js openGraph not inheriting?

The docs suggest pulling shared fields into a variable and spreading it into each page's openGraph. That works, but it leaves it to every page author to remember the spread. I had 55 case studies built from one template plus a few static pages, so I put the whole thing in a function in lib/social-meta.ts:

import type { Metadata } from 'next'
import { siteConfig } from '@/config/site'

type SocialMetaInput = {
  title: string
  description: string
  /** Root-relative path, resolved against the layout's `metadataBase`. */
  path: string
  images: NonNullable<Metadata['openGraph']>['images']
  /** Case studies are articles; set this and `og:type` becomes `article`. */
  article?: { modifiedTime?: string }
}

export function buildSocialMeta({
  title,
  description,
  path,
  images,
  article,
}: SocialMetaInput): Pick<Metadata, 'openGraph' | 'twitter'> {
  const shared = {
    siteName: siteConfig.name,
    locale: siteConfig.openGraph.locale,
    title,
    description,
    url: path,
    images,
  }
  const twitter: Metadata['twitter'] = {
    card: 'summary_large_image',
    site: siteConfig.twitterTag,
    creator: siteConfig.twitterTag,
    title,
    description,
  }
  if (!article) {
    return { openGraph: { ...shared, type: 'website' }, twitter }
  }
  return {
    openGraph: {
      ...shared,
      type: 'article',
      authors: [siteConfig.links.websiteUrl],
      ...(article.modifiedTime ? { modifiedTime: article.modifiedTime } : {}),
    },
    twitter,
  }
}

A page spreads the result into its metadata:

// app/projects/[slug]/page.tsx (after)
return {
  title: project.title,
  alternates: { canonical: `/projects/${slug}` },
  ...buildSocialMeta({
    title: `${project.title} | Mohamed Gado`,
    description,
    path: `/projects/${slug}`,
    images: [ogImage],
  }),
}

Because buildSocialMeta returns both objects complete, the shallow merge no longer matters: the page's openGraph replaces the layout's, and the replacement already contains everything the layout had. The site name, locale and handles come from siteConfig, the same source the layout reads, so they cannot drift apart.

The helper also gave me a single place to add article fields. Case studies now pass article, which sets og:type to article and adds article:modified_time and article:author.

One detail in the helper: I leave twitter.images unset on purpose. My code comment says Next falls back to the openGraph images, with alt text and dimensions included, so the image is declared once.

How do I stop it coming back?

A convention in a README does not survive the next new page. I added a check to the postbuild step. scripts/check-index-parity.ts reads every prerendered page and asserts that it carries og:site_name, og:locale and both Twitter handles. Before the fix it reported 57 failures. After, 0.

The rule written down in my lessons file is short: a page that sets openGraph or twitter goes through buildSocialMeta, and the build fails otherwise. Because the check runs on built HTML, it also catches pages I did not think of, such as a new route someone adds later and forgets to wire up.

What else should I check on pages that override metadata?

Other nested fields behave the same way. The docs name robots next to openGraph as a field that is overwritten wholesale. If a layout sets robots: { index: true, follow: true, googleBot: {...} } and one page sets robots: { index: false }, the page does not keep the googleBot block. Anything that is an object in the Metadata type is a candidate: alternates, icons, twitter, appLinks and so on.

For each one, ask whether the layout sets it and whether any page sets it again. If both are true, the page's version has to be complete. A helper function, a spread of a shared object, or a build-time check on the output are all workable. I picked the helper and the check together, since the helper prevents the mistake and the check proves it.

The change was small, and nothing on the site looked different afterwards. What changed was the HTML that link previews and search engines read for 57 pages. If you set openGraph on any page below your root layout, curl one of those pages today and look for og:site_name.

Discovered – currently not indexed in Search Console: what it means and what fixed it

Mohamed Gado — Wed, 11 Nov 2026 00:02:03 +0000

"Discovered – currently not indexed" means Google knows the URL exists but has not fetched it yet. On my portfolio, 50 project pages landed in that bucket at once, because a batch of thin, near-identical pages made Google spend no crawl effort on any of them. Cutting down to fewer, better pages got them moving, and below are the details and the mistakes I made on the way.

What does "Discovered – currently not indexed" mean?

Google found the URL, usually through a sitemap or a link, and put it in a queue. It has not crawled it. That differs from "Crawled – currently not indexed", where Google fetched the page and decided not to keep it.

So the status says nothing about your page's content yet, because Google never looked at it. It says Google chose not to spend a request on it. Two things push that decision: how worth crawling the site as a whole looks, and how many URLs showed up at once.

Why were 50 of my pages stuck there?

The 2026-08-09 Search Console export showed the not-indexed count jumping from 6 to 56 on 2026-07-25. Indexed pages had been frozen at 7 since 2026-07-01. The deploy on 2026-07-25 had cross-linked every project page, so all 53 appeared in front of Google at the same time.

About half of those pages were synced from the READMEs of old tutorial repositories. With code blocks stripped, they had between 22 and 190 words of prose, and several were byte-identical to each other. Google read the batch as thin, near-duplicate filler. It spent no crawl budget on any of it, including the projects that had real content.

A site's good pages get judged alongside its bad ones. If you add dozens of weak URLs at once, the strong ones queue behind them.

How do I fix pages stuck in Discovered – currently not indexed?

I fixed it in two passes.

Pages under a word floor, MIN_INDEXABLE_WORDS, set to 200, render noindex, follow and drop out of the sitemap and every other discovery surface. That cut the set I was asking Google to index from 53 to 32.
I wrote a hand-authored overview for the stub pages. It survives my README sync script, renders above the synced README, and counts toward the threshold. Twenty sidecars got one. The final state was 53 indexable pages and 0 noindex.

My first pass was only the first step. I noindexed 21 pages and reported the problem as solved. That relieved the crawl-budget symptom, but it also gave up on a third of the portfolio. Writing real content was the option that raised the indexed count (52 versus 32), and I should have offered it together with the threshold.

What does the "fewer, better pages" rule look like in code?

One predicate answers the question, and every surface imports it. The sitemap, the page's robots meta, llms.txt and the IndexNow submission all ask it:

export const MIN_INDEXABLE_WORDS = 200

export function isIndexableSidecar(sidecar: {
  overview?: string
  body: string
  seoIndex?: boolean
}): boolean {
  // An explicit override wins in either direction.
  if (typeof sidecar.seoIndex === 'boolean') return sidecar.seoIndex
  const words = countProseWords(`${sidecar.overview ?? ''}\n\n${sidecar.body}`)
  return words >= MIN_INDEXABLE_WORDS
}

listIndexableProjects() filters the project list through that function. Anything that promotes pages to Google reads that list, so no caller can disagree with the page's own robots tag.

The single predicate earned its place the hard way. For a while the word-count arithmetic was inlined in two files, and IndexNow counted the README body but not the new overview. It silently dropped three pages the sitemap listed. A build step that compares sitemap membership against each page's rendered <meta robots>, llms.txt and the IndexNow set caught it on its first run. Without that check, it would have turned into a Search Console mystery weeks later.

You can see the resulting pages on /projects, and the site itself is described in the portfolio case study.

Should I click "Request indexing" on every URL in the report?

No, and this is where I wasted the most time. Request Indexing has a small daily quota, about 10 a day, and the Pages report that lists your stuck URLs lags the live index.

On 2026-11-03 the Pages report showed 49 indexed and 24 not: 12 "Discovered", 6 "Crawled, not indexed", 4 redirects and 2 alternate canonicals. Live URL Inspection told a different story:

Of the 12 "Discovered" URLs, 11 were already on Google or had been requested the night before. Only /projects/portfolio had never been crawled.
Of the 6 "Crawled, not indexed" URLs, 5 were OG images and the favicon, which I noindex on purpose. The sixth, /projects/rafiq, was on Google.
The redirects were the http and apex variants of the home page, which is expected.

I had spent a request on /projects/angular-todo straight from the report's list, and it was already on Google. The Pages report can be days to weeks behind.

The same thing happened on a second site of mine. Six translated pages were listed as "Discovered, not indexed". Live inspection showed five of the six were already on Google, so one request was enough.

My rule now: inspect each URL live first, and request indexing only for the ones Google reports as unknown.

Does the Request Indexing quota reset at midnight?

I assumed it did and told myself the queue would be free the next day. One request went through at the start of the day, and then "Quota exceeded" came back. The quota frees as each request from the previous day ages out, so it works as a rolling window. Spread the queue across the day.

The quota is also per Google account, shared by every property you own. My other site hit "Quota exceeded" after 2 requests because the portfolio had used the rest.

On 2026-10-17 I requested indexing for 11 pages before the 12th returned "Quota exceeded".

What is the difference between "Something went wrong" and "Quota exceeded"?

"Quota exceeded" is the only quota message. On the seventh request of one session I got "Oops! Something went wrong ... Please try again later." and read it as the quota again. A single retry after dismissing it went through. Retry once before assuming you are out of quota.

What does "No referring sitemaps detected" mean?

For a page Google has never seen, the inspection can say "No referring sitemaps detected". I took that for a missing sitemap entry. The live sitemap had the URL, and Google had not re-read the sitemap since I added the page. Check your live sitemap before changing code.

What changed in the numbers?

Search Console between 2026-10-09 and 2026-10-17, after the fixes above:

	10-09	10-17
Indexed	18	28
Discovered, never crawled	42	32
Unknown to Google	n/a	1 (`postkit`, shipped 10-15)

By 2026-11-03 the Pages report showed 49 indexed. The redirects, a ?ref canonical and the noindexed images in the remaining rows were working as designed.

What should I check first on my own site?

Open each URL in URL Inspection and read the live status. The Pages report is a lagging summary.
Count the words of real prose on the pages in the bucket. If a large share are stubs or copies of each other, that is your answer.
Decide per page: write real content for it, or mark it noindex, follow and take it out of your sitemap and internal link lists.
Keep one function that decides what is indexable, and have the sitemap, the robots tag and any submission scripts all call it.
Request indexing only for URLs that inspection reports as unknown to Google, and spread the requests across days.

I also checked the site before blaming Google. A crawl of all 59 sitemap URLs on production with a Googlebot user agent returned a 200 on every page, each with a self-canonical, index, follow and one <h1>, and no duplicate titles or descriptions. When the site is clean and the bucket is still full, the cause is usually page quality or volume.

Why a CSS rotate with will-change: transform makes images and text blurry

Mohamed Gado — Wed, 11 Nov 2026 00:01:25 +0000

If an element is rotated or scaled and has will-change: transform, the browser can rasterise it once and then resample that bitmap every time it moves. Text and thin UI edges come out soft, and no amount of image quality fixes it. On my site, app screenshots looked pixelated because every card had a 0.9deg rotation under will-change: transform and a hover scale. Removing the tilt, the scale and the will-change made them sharp.

The report that started this was short: the images on the Masareef, Rafiq and Nafis project pages looked pixelated and bad. The files on disk were fine. Every screenshot was 1200px wide and sharp. The browser was blurring them on the way to the screen.

Why does will-change: transform make things blurry?

will-change: transform tells the browser to promote the element to its own compositor layer. That layer is drawn into a bitmap, and from then on the compositor moves, rotates and scales the bitmap on the GPU without repainting the content.

That is fast, and it is also the problem. A layer that is rasterised once, upright, has to be resampled to be turned. A bitmap that is resampled at an angle cannot keep a one-pixel edge crisp, and small text is made of one-pixel edges. My notes from the fix put it plainly: a rotated raster of small type is never sharp at any angle, and the angle only decides how much.

Scaling has the same cost. In my case the hover state scaled the card by 1.045 on that same layer. The layer was not re-rasterised at the new size, so the card under the cursor was an upscaled copy of its own bitmap. The one card the visitor was looking at was the softest on the page.

How did I confirm the cause?

I read computed style straight from production in the browser the report came from, a 1512px wide window at a device pixel ratio of 2. One evaluation returned three things: the transform matrix matrix(0.999877, -0.0157…), will-change: transform, and an image request for w=640&q=75. That was the diagnosis before I changed a line.

The matrix is what a rotation of about 0.9 degrees looks like: the cosine is close to 1 and the sine is about 0.0157. It is easy to dismiss that as "almost not rotated". The raster does not care how small the angle is.

The screenshots were part of a fanned deck. I had added the tilt earlier with a comment that kept it under a degree, because past that the captions baked into the images read as crooked. That earlier work measured the caption tops to within 3px. Nobody zoomed into the pixels on a 2x screen, so the blur was designed in and defended by a comment.

What did the CSS look like before and after?

Before, every card was a fanned, overlapping layer:

.shot {
  flex: 0 0 clamp(11rem, 44vw, 15rem);
  margin: 0 -1.5rem 0 0; /* overlap */
  transition: transform 0.28s cubic-bezier(0.2, 0.7, 0.3, 1);
  will-change: transform;
}
.shot:nth-child(odd)  { transform: rotate(-0.9deg); }
.shot:nth-child(even) { transform: rotate(0.9deg); }

.shot:hover,
.shot:focus-within {
  transform: rotate(0deg) translateY(-0.6rem) scale(1.045);
}

After, the cards are flat. No tilt, no scale, no will-change, and the hover lift is a plain translate that lands on whole pixels:

.shot {
  flex: 0 0 clamp(12rem, 58vw, 16.5rem);
  margin: 0;
}

.shot a.image-zoom {
  transition: translate 0.32s cubic-bezier(0.2, 0.8, 0.2, 1);
}

/* Lift, never scale: a whole-pixel translate is the one transform that does
   not resample the screenshot once it lands. */
.shot a.image-zoom:hover,
.shot a.image-zoom:focus-visible {
  translate: 0 -0.375rem;
}

The rule I wrote down afterwards: never rotate or scale raster content that carries small type, and never put will-change: transform on anything that scales. If a card needs to lift, translate it by a whole number of pixels.

Was it only the CSS?

No. There were three more causes, and the CSS was the biggest.

The images were AVIF at quality 75, which left ringing around small UI type. Quality 90 was clean for 6 KB more per card, 25 KB to 31 KB at 640px wide. The cards were also 240px wide, a phone screen shown at a fifth of its size, and clicking one opened the raw file in a new tab. I changed the cards to 264px on desktop and 58vw on a phone, cut the srcset to 384, 640 and 828 at quality 90, and opened a full-height viewer on click.

Because Next.js only serves widths and qualities listed in next.config.js, I added q=90 to images.qualities, and a test now reads that config and fails if any rendered image URL asks for a width or quality the optimizer would reject.

Why were the cover banners blurry as well?

A second report came the same day: "I meant this", with a screenshot of the cover banner at the top of the Masareef page, not the gallery. I had fixed the wrong images first. The lesson there was to look at the first viewport before deciding which images a report means.

The banner problem was about device pixels. The source art was a 1024x500 store graphic. The hero rendered 1086 CSS pixels wide, which is 2172 device pixels on a 2x screen, so the browser stretched the file by about 2.1 times. An earlier "hi-res" version at 2560px wide was an upscale of the same 1024 pixels, so it was soft too, only larger. The file size had been the clue: 75 KB for 2560 pixels of supposed detail.

The check I keep now is to compare a raster's intrinsic width with the rendered width multiplied by the device pixel ratio, in device pixels and not CSS pixels. I redrew the covers from SVG at 3x, which gave a 3072x1500 source, and fixed the sizes attribute, which had assumed a 768px column when the header was 1086px wide.

When should text be an image and when should it be live text?

Redrawing the banner at 3x fixed the 2x screen and exposed the next problem a few hours later. A screenshot of the hero at about 1x showed the wordmark and tagline soft next to the real text above them. At 1x the browser was shrinking 3072 pixels into 768, and shrunk type is filtered just like stretched type.

No file size fixes that, because the words were pixels. I had answered "pixelated" with more pixels twice. The question to ask on the first report is whether the thing is text.

The hero of the five mobile app pages is now live HTML in components/projects/app-banner.tsx: the name, the Arabic name, an accent rule and the tagline are real text over a CSS background of two radial glows and a light SVG grain to avoid banding. The app icon is the only image. The frame is a query container, so the type scales with its own width and one rule covers both the 768px column and a 310px phone column.

The rule that came out of it: text a reader has to read is live text. A raster of type belongs only where the page cannot draw text, such as link-preview cards and store listings. The same lesson says to check sharpness at the pixel density of the screenshot you were sent. My test rig had emulated a 2x laptop, where the 3x cover looked fine, and the report came from a screen at about 1x.

A checklist for blurry images and text in CSS

Search the stylesheet for will-change: transform and for any rotate() or scale() on elements with images or text. Remove them from anything that carries small type.
Read the computed transform in devtools. A matrix that is not the identity on a card you thought was flat is a lead.
Compare the image's intrinsic width with rendered width times device pixel ratio.
Test at 1x and at 2x. A fix that is sharp at one density can be soft at the other.
If the blurry thing is text, make it text.

You can see the finished pages on the Masareef, Rafiq and Nafis case studies. The site they live on is described in the portfolio write-up.