No layout shift: a page paints whole
No layout shift: a page paints whole
A page must not move when its data arrives. Found on 2026-11-09 in RunMist (built on this template) across a dozen settings tabs: cards appeared late and moved the grid, sections showed a one-line "Loading..." and then swapped in the real content, and a dropdown backed by a provider API appeared seconds after the page.
Every case was the same mistake: a component inside a route fetched its
own data on mount (useQuery), and until it came rendered something of a
different size: nothing (if (!data) return null), or a short loading
line (if (isLoading) return <p>Loading...</p>).
The rule
-
Local data (a DB read, milliseconds): prefetch it in the route loader. Every query a page renders, including the ones inside cards and sections, goes in that route's
loaderthrough itsqueryOptionsfactory. The component reads the same factory, so the data is in the cache on first paint and the loading branch never shows.loader: async ({ params, context }) => { const { queryClient: qc, workspaceId } = context as AppRouteContext; await Promise.all([ qc.prefetchQuery(projectQueryOptions(workspaceId, params.projectId)), // the stats card inside the page, too qc.prefetchQuery(projectStatsQueryOptions(workspaceId, params.projectId)) ]); }, -
Slow external data (a provider API, SSH, seconds): never block the page on it, and keep its place. Start it in the loader without awaiting (
void qc.prefetchQuery(...)), and render the control at its final size while it loads: a disabled select with "Loading sizes...", a skeleton the size of the card. Cache what rarely changes on the server (RunMist caches a provider's server types for an hour). -
Factories in their own file when a component uses them. A factory in the feature barrel that a component of the same feature imports is a circular import (the barrel re-exports the component). Put it in
src/features/<feature>/<name>-query.tsand re-export it from the barrel for routes.
The check
make check-layout-shift (in make ci, scripts/check-layout-shift/)
flags, in any component that calls useQuery/useInfiniteQuery:
-
if (!data) return null;on a variable destructured from a query -
an early return on a loading flag (
if (isLoading) {,if (isPending) return null,if (loadingItems) {) -
an empty state on a query's
data: items = []default (items.length === 0,!items.length) when the line doesn't show the query finished. While loading, the default is empty, so "Nothing here yet" (or a setup banner) flashes before the real list. Gate it onisSuccess(or a...Loadedflag):{loaded && items.length === 0 && <Empty />}. Found on 2026-11-09 as the "Connect a cloud provider" banner flashing on every dashboard load. -
a query written inline,
useQuery({ queryKey, queryFn }), in a component. No loader can prefetch it, so whatever renders on its data ({item && <Result />}, a ternary) appears after the page does. Move it to aqueryOptionsfactory (in the feature's own*-query.tswhen the barrel also re-exports the component) and prefetch that in the route loader. A spread factory,useQuery({ ...fooQueryOptions(id), enabled }), is not flagged. Found on 2026-11-10 in RunMist (built on this template): 20 inline queries, two of which stored a rawResultunder the same key a factory stored the unwrapped list, so one page always read it as empty.
A hit is fine once the route loader prefetches that query, or the fallback
keeps the same size: say which with // layout-ok: <reason> on that line
or the one above. The check can't see a page's loader, so the comment is
the record that someone looked.
It does not catch everything: {data && <Card />} and ternaries that swap
sizes also shift the layout. Look for those in review.
Browser-only data. better-auth's client (authClient.listSessions(),
listAccounts()) can't run during SSR, so a page reading it can't be
prefetched and suspends on every visit: the whole page went blank moving
from Settings to Account. Read it through a server function instead
(auth.api.listSessions({ headers: getRequestHeaders() }), see
features/account/server/account.queries.ts), and prefetch that.