Join the waitlist

Gamestage UI

Components for the interface a live game wears: choices, score, timer, rewards and the leaderboard.

Gamestage UI provides React components for a game's controls and status: choices, scores, timers, rounds, streaks, rewards and leaderboards. They draw over your own video, canvas or 3D scene, which stays yours.

The installer copies each component into your project as source. You can edit it, and nothing changes under you until you run update.

Install a component

The Gamestage UI Get started guide takes a new Vite, React and TypeScript app to a working question, and is the tested route. The first command is:

npx gamestage-ui@0.1.0 add choice theme-arcade

The registry is public, so there is no account or token to set up. In a project that keeps its source in src/, the component lands under src/components/gamestage/ and the shared stylesheets under src/app/. The installer prints the stylesheets to import, and leaves an existing file alone unless you pass --overwrite.

If you see "not found", run npx gamestage-ui list and use the exact name it prints.

CommandWhat it does
npx gamestage-ui add <name...>Copies components in, with what they depend on
npx gamestage-ui listPrints every component the registry serves
npx gamestage-ui diff / updateShows, then takes, our changes to files you have not edited
npx gamestage-ui initWrites gamestage.json, which pins the registry URL and install directory

init is optional and not part of a first install. A private registry is named with --registry <url> or in gamestage.json, with GAMESTAGE_REGISTRY_TOKEN set to a token that can read it.

A question on screen

import { useState } from 'react'
import { Choice, type ChoiceResult } from './components/gamestage/choice'

export function Question() {
  const [result, setResult] = useState<ChoiceResult>()

  function handleAnswer(ids: string[]) {
    const id = ids[0]
    if (!id) return
    setResult({ [id]: id === 'ver' ? 'correct' : 'wrong' })
  }

  return (
    <Choice
      label="Which driver led the most laps?"
      presentation="buttons"
      commitOnSelect
      result={result}
      options={[
        { id: 'ver', label: 'Verstappen' },
        { id: 'nor', label: 'Norris' },
        { id: 'lec', label: 'Leclerc' },
      ]}
      onCommitted={handleAnswer}
    />
  )
}

That renders three answers, records the pick and shows the result your app passes back. Change presentation to show the same question as cards, a list, a wheel or an overlay over a live scene.

What your app does

The components do not call your API or store player data. Your app handles these tasks:

The components do notYour app does
Sign anyone inPass the player you already have
Store progressPersist it wherever you keep state
Call your APICall it from the callbacks
Decide who wonSettle the outcome and pass it back
Ask for consentRender your own consent screen
Send analyticsForward the callbacks to your own tracking

Gamestage UI sits beside the Engine. The Engine decides whether a play was any good and holds the score; Gamestage UI draws what the Engine decided. You can use either on its own.

Theming

Every colour, size, duration and typeface is a token. Components read tokens and never define their own, so changing a token changes every surface at once.

<html data-gs-theme="arcade" data-gs-context="light">

A theme changes the palette, the typefaces, the corner radius, the edge treatment, and what a control does when you press it: travel on an offset base, scale, or hold still and shift colour instead. Three themes ship today: arcade, paper and stadium. To make your own from your brand's Figma file and publish it for your organisation, see make your organisation's theme.

Selecting on it from outside

Components describe themselves with data-gs-* attributes, so your code and your tests find things without depending on class names or on the words on screen. A theme changes the first and a translation changes the second.

[data-gs-part="label"]                       /* every label, everywhere */
[data-gs-scope="stat"][data-gs-part="label"] /* only a stat's */
[data-gs-state="wrong"]                      /* a settled wrong answer */

Those attributes are public API. One is documented before it is emitted, and a gate check fails the build when the documentation and the components disagree.

What the registry serves

Grouped by what it's for. The groups are the library's own: each item declares its category, and the Gallery at ui.gamestage.ai reads the same field, so what you see there and what you read here cannot disagree. New items ship often; treat this as a sample rather than a count.

GroupItems
Controlsbutton, choice, selector, slider, toggle
Playeridentity, player-card, presence, profile
Game statehud, lives, multiplier, round, score, stat, streak, timer
Progresslevel-ring, milestones, progress-bar, quest, segments
Rewardsinventory, reward
Competitionleaderboard, podium, versus
Chartschart (bar, line, area, radial)
Flow and guidancecoach-mark, onboarding, tip, tutorial-step
Mediamedia-frame, story
Game feelfeedback
Compositionnav, stage
Application surfacescode-entry, consent, discovery, empty-state, error-state, field, form, login, prize-entry, recovery-code, sponsor
Foundationsadapter, cues, fonts, fonts-arcade, fonts-paper, theme-arcade, theme-paper, theme-stadium, tokens

glyphs is in the registry, ungrouped.

You rarely name the last two rows. Application surfaces are whole screens rather than parts of one, and Foundations are the tokens, typefaces, themes and the host adapter that other items pull in for themselves, so asking for choice brings what it needs without you listing it.

npx gamestage-ui list prints what the registry holds today, which is the list to trust over this one.

Three things arrived in the registry on 28 September. nav takes presentation="glass" and labels="hidden" for an icon-only bar. story takes gestures (tap, swipe across, swipe down to close) and fullscreen. And every pressable control presses down under a thumb on an iPhone and never selects its words.