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>

Tip

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.