LoadingScreen

LoadingScreen is a pre-built, customizable loading screen component designed to work with AssetLoader. It renders as HTML content within the AssetLoader's fallback slot.

tsx

import { LoadingScreen } from "@carverjs/core/components";

Quick Start #

tsx

import { Game, World, Actor, AssetLoader, LoadingScreen } from "@carverjs/core/components";

function App() {
  return (
    <Game>
      <AssetLoader
        manifest={[{ url: "/models/hero.glb" }]}
        fallback={(progress) => <LoadingScreen progress={progress} />}
      >
        <World>
          <Actor type="model" src="/models/hero.glb" />
        </World>
      </AssetLoader>
    </Game>
  );
}

Themes #

Default #

Minimal progress bar with percentage text.

tsx

<LoadingScreen progress={progress} theme="default" />

Gaming #

Wider progress bar with asset names, loaded count, rotating tips, and error display.

tsx

<LoadingScreen
  progress={progress}
  theme="gaming"
  logo="/logo.png"
  tips={[
    "Use WASD to move",
    "Collect coins for points",
    "Try Hard mode for a real challenge",
  ]}
  tipInterval={4000}
/>

Minimal #

Spinner animation with percentage.

tsx

<LoadingScreen progress={progress} theme="minimal" />

Custom #

Full control via children render prop. No default UI is rendered.

tsx

<LoadingScreen progress={progress} theme="custom">
  {(p) => (
    <div style={{ fontSize: 24, color: "#fff" }}>
      {Math.round(p.progress * 100)}% — {p.currentAsset ?? "Ready"}
    </div>
  )}
</LoadingScreen>

Props Reference #

Prop	Type	Default	Description
`progress`	`LoadingProgress`	—	Required. Loading progress data from AssetLoader's render prop
`theme`	`"default" \| "gaming" \| "minimal" \| "custom"`	`"default"`	Visual theme preset
`background`	`string`	`"#000000"`	CSS background color or value
`accentColor`	`string`	`"#6366f1"`	Progress bar accent color
`logo`	`string \| ReactNode`	—	Logo URL or React element displayed above the bar
`tips`	`string[]`	—	Loading tips to cycle (gaming theme)
`tipInterval`	`number`	`5000`	Tip rotation interval in ms
`showCurrentAsset`	`boolean`	`true`	Show the name of the asset being loaded
`showCount`	`boolean`	`true`	Show loaded/total count (e.g., "12/20")
`children`	`(progress: LoadingProgress) => ReactNode`	—	Custom render function (custom theme)

Customization Examples #

Branded loading screen #

tsx

<LoadingScreen
  progress={progress}
  theme="gaming"
  background="#1a1a2e"
  accentColor="#e94560"
  logo={<h1 style={{ color: "#e94560", fontSize: 36 }}>My Game</h1>}
  tips={["Press Space to jump", "Watch out for enemies"]}
/>

Fully custom layout #

tsx

<AssetLoader
  manifest={manifest}
  fallback={(progress) => (
    <div style={{
      position: "absolute", inset: 0,
      display: "flex", alignItems: "center", justifyContent: "center",
      background: "#000", color: "#fff", fontFamily: "monospace",
    }}>
      <div>
        <img src="/logo.png" alt="Logo" style={{ width: 200, marginBottom: 20 }} />
        <div style={{ width: 300, height: 4, background: "#333", borderRadius: 2 }}>
          <div style={{
            width: `${progress.progress * 100}%`,
            height: "100%",
            background: "#6366f1",
            borderRadius: 2,
            transition: "width 0.3s",
          }} />
        </div>
        <p style={{ marginTop: 12, fontSize: 14, opacity: 0.7 }}>
          {Math.round(progress.progress * 100)}%
        </p>
      </div>
    </div>
  )}
>
  {children}
</AssetLoader>

You don't have to use `LoadingScreen` at all. The `fallback` render prop on `AssetLoader` accepts any React element. Use `LoadingScreen` for quick setup, or write your own UI from scratch.

Type Definitions #

See Types for LoadingProgress and AssetLoadError.