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

  1. 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 loader through its queryOptions factory. 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))
      ]);
    },
    
  2. 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).

  3. 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.ts and 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 on isSuccess (or a ...Loaded flag): {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 a queryOptions factory (in the feature's own *-query.ts when 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 raw Result under 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.