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-arcadeThe 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.
| Command | What it does |
|---|---|
npx gamestage-ui add <name...> | Copies components in, with what they depend on |
npx gamestage-ui list | Prints every component the registry serves |
npx gamestage-ui diff / update | Shows, then takes, our changes to files you have not edited |
npx gamestage-ui init | Writes 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 not | Your app does |
|---|---|
| Sign anyone in | Pass the player you already have |
| Store progress | Persist it wherever you keep state |
| Call your API | Call it from the callbacks |
| Decide who won | Settle the outcome and pass it back |
| Ask for consent | Render your own consent screen |
| Send analytics | Forward 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.
| Group | Items |
|---|---|
| Controls | button, choice, selector, slider, toggle |
| Player | identity, player-card, presence, profile |
| Game state | hud, lives, multiplier, round, score, stat, streak, timer |
| Progress | level-ring, milestones, progress-bar, quest, segments |
| Rewards | inventory, reward |
| Competition | leaderboard, podium, versus |
| Charts | chart (bar, line, area, radial) |
| Flow and guidance | coach-mark, onboarding, tip, tutorial-step |
| Media | media-frame, story |
| Game feel | feedback |
| Composition | nav, stage |
| Application surfaces | code-entry, consent, discovery, empty-state, error-state, field, form, login, prize-entry, recovery-code, sponsor |
| Foundations | adapter, 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.