React frontend

The React side of a route renders the UI. It receives typed data from the route's Rust handler, composes with layouts, and navigates on the client - while the data loading stays in Rust.

Page components

A page.tsx default-exports a React component. Its props are whatever the route's page.rs handler returns, spread directly onto the component. To type them, annotate the component with OssidoPage from the generated @ossido-labs/ossido/types module:

import type { OssidoPage } from '@ossido-labs/ossido/types';

// `subtitle` is exactly this route's page.rs handler return type.
const HomePage: OssidoPage<'/'> = ({ subtitle }) => {
  return <h1>{subtitle}</h1>;
};

export default HomePage;

OssidoPage<Path> takes the route's URL path as its type argument - '/', '/documentation', '/pokemons/[pokemon]' - and resolves to a component whose props match that route's handler return value. The available paths are generated from your src/routes tree, so the argument autocompletes and an unknown path is a type error. A page with no page.rs handler simply has empty props. (See TypeScript integration for how these types are generated.)

Layouts & children

A layout.tsx wraps the routes beneath it and renders their children. The root layout owns the document shell; nested layouts wrap a subtree.

For a layout that only wraps its children, type it with OssidoLayoutProps from @ossido-labs/ossido:

import type { OssidoLayoutProps } from '@ossido-labs/ossido';

export default function DocsLayout({ children }: OssidoLayoutProps) {
  return <div className="docs-shell">{children}</div>;
}

A layout can also load its own data with a layout.rs handler. When it does, type the component with OssidoLayout<'/path'> from @ossido-labs/ossido/types instead - it gives you the handler's data and children, both typed:

import type { OssidoLayout } from '@ossido-labs/ossido/types';

const DocsLayout: OssidoLayout<'/documentation'> = ({ section, children }) => (
  <div>
    <nav>{section}</nav>
    {children}
  </div>
);

export default DocsLayout;

The <Path> argument works just like OssidoPage's - it's the route path, and the props resolve to that layout's handler data. See Layout handlers for the layout.rs side.

Client navigation

Use Link from @ossido-labs/ossido for in-app navigation - it keeps you in the SPA (fetching just the next route's props) instead of a full page load:

import { Link } from '@ossido-labs/ossido';

<Link href="/documentation/cli">CLI docs</Link>;

Link accepts the usual anchor attributes plus:

• preload (default true) - load the target route when the link scrolls into view. Set false to opt out.
• scroll (default true) - scroll to the top on navigation; false keeps the offset.
• replace (default false) - replace the history entry instead of pushing.

Router hooks

useRouter exposes the current location, programmatic navigation, and a way to refresh the current page's data:

import { useRouter } from '@ossido-labs/ossido';

function SearchBox() {
  const { pathname, query, push, replace } = useRouter();
  // pathname → current path, query → query-string params
  return <button onClick={() => push('/documentation')}>Docs</button>;
}

push adds a history entry; replace swaps the current one. Dynamic segment values (from [param] routes) reach the page through its server props rather than a hook - have the handler include them in what it returns.

Refetching props

refetchProps() re-runs the current route's page.rs handler and re-renders the page with the fresh data - without a full navigation. Reach for it after a mutation, when the values the page was server-rendered with have changed and you want it to reflect them. The current page stays on screen while the refetch is in flight (no loading.tsx flash), and isRefetching is true until it resolves:

import { useRouter } from '@ossido-labs/ossido';

function RefreshButton() {
  const { refetchProps, isRefetching } = useRouter();

  return (
    <button onClick={() => refetchProps()} disabled={isRefetching}>
      {isRefetching ? 'Refreshing...' : 'Refresh'}
    </button>
  );
}

Head & metadata

This is React 19, so document metadata is native: render <title>, <meta>, or <link> anywhere in a component and React hoists them into <head>. Set site-wide defaults in the root layout, and per-page tags in the page itself:

const PokemonPage: OssidoPage<'/pokemons/[pokemon]'> = ({ name }) => (
  <>
    <title>{`Pokémon: ${name}`}</title>
    <h1>{name}</h1>
  </>
);

Loading & error UI

• loading.tsx is rendered as a <Suspense> fallback while a route's data resolves.
• Errors thrown during render - or a failing Rust handler - are caught and shown as the error page (a detailed overlay in development). See Error Handling for customizing that, and not-found.tsx for unmatched routes.

Hydration

On first load the server streams fully-rendered HTML, then the client bundle hydrates it into a live React app. To hydrate without re-fetching, the server injects a payload - window.__OSSIDO_SERVER_PAYLOAD__ - carrying the initial location and the route's data; the OssidoScripts element in the root layout emits it along with the client entry. Because the client renders from that same data, its output matches the server's markup.

Code-splitting & preloading

Every route is code-split and lazily loaded, so the browser only downloads the code for the pages it visits. Link warms the next route automatically when it scrolls into view (the preload prop), and preloadRouteChain lets you preload a route's code manually.

For component-level lazy loading, dynamic wraps React.lazy + Suspense:

import { dynamic } from '@ossido-labs/ossido';

const Chart = dynamic(() => import('@/components/Chart'), {
  ssr: false, // client-only
  loading: () => <p>Loading chart...</p>,
});

Next: Typed API client · TypeScript integration