Runtime Status

Advanced, you usually don’t need this

<ToriiProvider> and the drop-in components (<SignIn>, <SignUp>, <UserDashboard>, …) already gate themselves on the runtime: while the SDK’s UI bundle is loading, or if it fails to load, they render nothing. So in the normal case you don’t touch any of this.

These components are a granular escape hatch for when you want to render your own loading or error chrome (a spinner, or a “couldn’t load, retry” message) in place of that default “render nothing.” The SDK ships no built-in error screen, so a failed runtime is invisible unless you opt in with <ToriiFailed>.

The SDK’s rendering primitives and their CSS are delivered from the CDN. These three components gate their children on whether that runtime is loading, ready, or failed, distinct from the auth lifecycle that drives <SignedIn> / <SignedOut> / <AuthLoading>.

All three must be rendered inside <ToriiProvider>.

Overview

Component	Renders children when…
<ToriiLoading>	The runtime is still loading.
<ToriiLoaded>	The runtime loaded and its styles are injected.
<ToriiFailed>	The runtime failed to load.

ToriiLoading

Renders its children while the SDK runtime is still loading.

import { ToriiLoading } from '@torii-js/torii-react';

<ToriiLoading>
  <FullPageSpinner />
</ToriiLoading>

Props

Name	Type	Default	Description
children	ReactNode	n/a	Rendered while the runtime is loading.

ToriiLoaded

Renders its children once the runtime has loaded and its styles are injected.

import { ToriiLoaded, SignedOut, SignIn } from '@torii-js/torii-react';

<ToriiLoaded>
  <SignedOut>
    <SignIn />
  </SignedOut>
</ToriiLoaded>

Props

Name	Type	Default	Description
children	ReactNode	n/a	Rendered once the runtime is ready.

ToriiFailed

Renders its children when the runtime fails to load. children may be plain nodes or a render function receiving the load error and a retry callback, so you can offer a retry button.

import { ToriiFailed } from '@torii-js/torii-react';

<ToriiFailed>
  {({ error, retry }) => (
    <div role="alert">
      <p>Couldn't load the sign-in UI. {error?.message}</p>
      <button onClick={retry}>Retry</button>
    </div>
  )}
</ToriiFailed>

Props

Name	Type	Default	Description
children	ReactNode | ((state: { error: Error | null; retry: () => void }) => ReactNode)	n/a	Rendered on load failure. As a function, receives { error, retry }.

useRuntimeStatus

The three components are thin wrappers over the useRuntimeStatus() hook, which exposes the same lifecycle for fully custom chrome.

import { useRuntimeStatus } from '@torii-js/torii-react';

function Gate({ children }) {
  const { status, error, retry } = useRuntimeStatus();
  if (status === 'loading') return <Spinner />;
  if (status === 'error') return <button onClick={retry}>Retry: {error?.message}</button>;
  return children;
}

Member	Type	Description
status	'loading' | 'ready' | 'error'	'loading' until the CDN runtime resolves, then 'ready' or 'error'.
error	Error | null	The load error when status === 'error', otherwise null.
retry	() => void	Re-attempt a failed load. No-op while loading or once ready.

Outdated runtime

Separately from “loading / ready / failed”, a runtime that did load can later become outdated: if Torii ships a breaking change to an endpoint and this tab is still running an older runtime, the server replies 426 and the SDK can no longer talk to that endpoint until the page reloads.

<ToriiProvider> handles this for you, no setup required: it shows a small “a new version is available, please refresh” banner (a reserved, label-driven prompt) and reloads the page when the user clicks it. The strings come from the runtimeOutdatedMessage / runtimeOutdatedRefreshButton labels.

To render your own UI instead, read the flag from useAuth():

import { useAuth } from '@torii-js/torii-react';

function OutdatedBanner() {
  const { runtimeIncompatible } = useAuth();
  if (!runtimeIncompatible) return null;
  return (
    <div role="alert">
      A new version is available. <button onClick={() => location.reload()}>Refresh</button>
    </div>
  );
}

Member	Type	Description
runtimeIncompatible	boolean	true once the server reports this runtime is too old for an endpoint. The default prompt renders automatically; read this to render your own.

The default banner component is also exported as RuntimeOutdatedPrompt if you want to reuse its markup with your own trigger.

Props

Name	Type	Default	Description
message	string	n/a (required)	The text explaining a reload is needed.
refreshLabel	string	n/a (required)	Label for the reload button.
onRefresh	() => void	n/a (required)	Invoked when the user clicks the reload button.

The default prompt rendered by <ToriiProvider> sources message and refreshLabel from the runtimeOutdatedMessage / runtimeOutdatedRefreshButton labels; supply your own strings when reusing the component directly.

import { RuntimeOutdatedPrompt, useAuth } from '@torii-js/torii-react';

function OutdatedBanner() {
  const { runtimeIncompatible } = useAuth();
  if (!runtimeIncompatible) return null;
  return (
    <RuntimeOutdatedPrompt
      message="A new version is available."
      refreshLabel="Refresh"
      onRefresh={() => location.reload()}
    />
  );
}

Server-side rendering

The runtime is client-only: loadRuntime never resolves on the server, so the server snapshot is a stable 'loading'. Gated widgets render null during SSR and hydrate cleanly once the client runtime resolves.

TypeScript

import type {
  ToriiFailedProps,
  RuntimeLoadStatus,
  RuntimeOutdatedPromptProps,
  RuntimeStatusSnapshot,
  UseRuntimeStatusReturn,
} from '@torii-js/torii-react';