@k8ordo/router

Errors and loading

With error and loading in the route table, you can show an error view when a page throws while rendering, and a loading view until it is ready. Pages split out with React.lazy are covered too.

On this page

Error display

src/routes.ts
export const routes = defineRoutes({
  '/products': {
    layout: ProductsLayout,
    error: ProductsError,
    children: {
      '/': ProductList,
      '/:id': ProductPage,
    },
  },
});
src/products-error.tsx
import type { ErrorProps } from '@k8ordo/router';

export function ProductsError({ error, reset }: ErrorProps) {
`error` is what was thrown, `reset` renders again
  const message =
    error instanceof Error ? error.message : 'Something went wrong';

  return (
    <div role="alert">
      <p>{message}</p>
      <button onClick={reset} type="button">
        Try again
      </button>
    </div>
  );
}

An object with children can have an error. When a page below it throws while rendering, the error component shows in its place. It renders where the layout puts <Outlet />, and the layout stays on screen.

error is typed unknown. Calling reset() renders the page below again, in place. If it throws again, the error component comes back.

The error goes away when you move to another page, at the moment that page is on screen. Layouts below the object are not recreated either, and keep their state. An update that changes only the query is not a page change, so the error stays.

Information

Note

A layout that throws is not caught by its own object’s error, because the error component renders inside the layout. The error is caught by the error of an object further out, and propagates out of <Router> when there is none.

Loading display

src/routes.ts
export const routes = defineRoutes({
  '/products': {
    layout: ProductsLayout,
    error: ProductsError,
    loading: ProductsLoading,
    children: {
      '/': ProductList,
      '/:id': ProductPage,
    },
  },
});
src/products-loading.tsx
export function ProductsLoading() {
  return <p role="status">Loading products…</p>;
}

loading names the component to show while a page below it suspends. It receives no props.

A <Suspense> goes where loading is written, with the loading component as its fallback. With an error beside it, this <Suspense> sits inside the error boundary.

The fallback shows when the page is first opened, and when you arrive from a page outside this object. Moving between pages already inside the object keeps the previous page on screen until the next one is ready. To show a loading state during that time, use usePendingPathname, covered in Location.

Code splitting a page

src/routes.ts
import { defineRoutes } from '@k8ordo/router';
import { lazy } from 'react';

const Settings = lazy(() => import('./pages/settings'));

export const routes = defineRoutes({
  '/': {
    layout: Shell,
    loading: PageLoading,
    children: {
      '/': Home,
      '/settings': Settings,
    },
  },
});

A page component can be wrapped in React.lazy and written into the route table. Its code loads the first time the page renders.

While the code loads, the fallback of the nearest <Suspense> above shows. Write a loading, or wrap <Outlet /> in a <Suspense> inside a layout, so there is somewhere to fall back to.

The fallback shows at the same moments as loading. In the example, the / object wraps every page. Opening /settings directly shows the fallback, while moving there from the home page keeps the home page on screen until the code has loaded.

Warning

Pitfall

An object with an error also wraps what is below in a <Suspense> whose fallback is null. A React.lazy page that suspends below it never reaches a layout’s <Suspense> above, and nothing shows. To show a fallback, give the same object a loading, or put a <Suspense> further down.

k8ordo

React libraries that use Baseline features without holding back.