WelcomeScreen
Navigation & Chrome

WelcomeScreen

Displays a setup entry screen with cycling greetings, branding, and actions.

Component behavior

WelcomeScreen displays a greeting, branding, descriptive text, and entry actions before setup. Greetings occupy a fixed-height area. Cycling starts after hydration and is disabled by prefers-reduced-motion.

Use cases
  • An initial screen before a setup wizard.
  • Entry actions for account, workspace, or import setup.
  • Kiosk or appliance idle screens.
Alternatives

Wizard: the user must answer form questions.

EmptyState: content is embedded within an existing page layout.

LoginPanel: the initial task is authentication.

Greeting changes use a crossfade with vertical motion. The incoming greeting begins fading after the first third of the transition; the outgoing greeting finishes by two thirds. Transition duration scales with the hold interval.

Props

WelcomeScreenProps props
PropTypeDefaultDescription
greetingsReactNode[]DEFAULT_WELCOME_GREETINGSGreetings displayed one at a time.
greetingDurationMsnumber2400Greeting display duration, in milliseconds. Values below 400 are clamped to 400.
cycleGreetingsbooleantrueWhen false, displays the first greeting. Server rendering and reduced-motion mode also display the first greeting.
brandReactNode—Logo mark above the greeting.
productNameReactNode—Product name below the greeting.
descriptionReactNode—Description below the product name.
actionsReactNode—Action content below the description.
footerReactNode—Footer content at the bottom of the screen.
background"glow" | "grid" | "plain" | "none""glow"Background style shared with Stage.
fullHeightboolean—Fills its parent instead of sizing to its content.
onGreetingChange(index: number) => void—Fires on every change of greeting, with its index.
childrenReactNode—Rendered between the description and the actions.

Examples

A first-run screen

WelcomeScreen
Switch

cycleGreetings={false} keeps the first greeting visible. The server and reduced-motion mode also display the first greeting.

Custom greetings

DEFAULT_WELCOME_GREETINGS is exported and can be reordered, filtered, or replaced.

GreetingsTSX
import { WelcomeScreen, DEFAULT_WELCOME_GREETINGS } from "@solarius/onset";

// Only the locales this build ships.
<WelcomeScreen greetings={["Welcome", "Bienvenue", "Willkommen"]} />

// Or the first eight of the bundled list, held a little longer.
<WelcomeScreen
  greetings={DEFAULT_WELCOME_GREETINGS.slice(0, 8)}
  greetingDurationMs={3200}
/>

Server rendering

  • The server and the first client render both show greetings[0]. Cycling starts after hydration, through useHydrated — the same pattern Timestamp and RelativeTime use.
  • No clock, timezone or platform reads any part of the markup, so the server render is deterministic.
  • Under prefers-reduced-motion the greeting neither cycles nor fades.

Import

ImportTSX
import { WelcomeScreen, DEFAULT_WELCOME_GREETINGS } from "@solarius/onset";
import type { WelcomeScreenProps } from "@solarius/onset";

const [begun, setBegun] = useState(false);

return begun ? (
  <Wizard steps={steps} onFinish={install} bordered={false} />
) : (
  <WelcomeScreen
    fullHeight
    actions={
      <Button variant="primary" onClick={() => setBegun(true)}>
        Get started
      </Button>
    }
  />
);