useRuntimeStatus

useRuntimeStatus() reports the load lifecycle of the SDK runtime: the UI primitives and their CSS, delivered from the CDN.

Advanced, you usually don’t need this

<ToriiProvider> and the drop-in components already gate themselves on the runtime, while it loads or if it fails, they render nothing. This hook (and the <ToriiLoading> / <ToriiLoaded> / <ToriiFailed> components) is a granular escape hatch for replacing that default with your own loading or error chrome.

When to use it

• Show a spinner or a retry button while the CDN runtime is in flight.
• Surface a load failure to the user (the SDK shows nothing by default).

The <ToriiLoading> / <ToriiLoaded> / <ToriiFailed> control components cover the common cases declaratively; reach for this hook when you need fully custom logic.

Usage

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

function RuntimeGate({ children }) {
  const { status, error, retry } = useRuntimeStatus();

  if (status === 'loading') return <Spinner />;
  if (status === 'error')
    return (
      <div role="alert">
        Failed to load: {error?.message}
        <button onClick={retry}>Retry</button>
      </div>
    );

  return children;
}

Returns

Name	Type	Description
status	RuntimeLoadStatus	'loading' until the CDN runtime resolves, then 'ready' or 'error'. During SSR it is a stable 'loading'.
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.

TypeScript

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