@sagegames/react

Verified mini-games for React web apps: Quiz Master, Memory Match, Sudoku Arena, Word Search and Word Rush, plus live battles for 2 to 16 players. The app never reports a score. It sends the player's moves, and the SageGames server replays them to compute the score.

• Plain DOM (CSS grid, pointer events, keyboard play for Sudoku). No react-native-web.
• React 18/19.
• The same API as @sagegames/react-native.

Full documentation: https://<api-host>/portal/docs, also as plain Markdown at /portal/docs/llms.txt. The source is at github.com/AnalytixTech/sage-game-platform.

Install

npm install @sagegames/react

Use

Your backend creates a session with your API key (POST /v2/sessions) and returns it to the browser. The API key never goes into the page.

import { allGames, createTheme, GameLauncher, SageGameProvider } from '@sagegames/react';

const theme = createTheme({ brand: '#7c3aed', mode: 'light' });

export function Play({ gameId, onDone }: { gameId: string; onDone: () => void }) {
  return (
    <SageGameProvider games={allGames} baseUrl="https://sage-game-platform.onrender.com" theme={theme} pendingStore={window.localStorage}>
      <GameLauncher
        getSession={() => fetch('/api/games/session', { method: 'POST', body: JSON.stringify({ gameId }) }).then((r) => r.json())}
        onComplete={(result) => console.log('verified', result.score, result.rank)}
        onClose={onDone}
      />
    </SageGameProvider>
  );
}

GameLauncher runs the whole flow: intro, the game, a review of the finished board, the verified result and the leaderboard. It handles pause, quit, retries and "Play again". MatchLauncher runs a battle: lobby, countdown, live race and standings.

Provider props

| Prop | | | --- | --- | | games | Usually allGames. Pass a subset, or replace a game's View. | | baseUrl | The SageGames API origin. | | theme, themeOverrides | A preset (arcadeTheme, darkNavyTheme, lightTheme, minimalTheme), createTheme({ brand }), or a partial theme, plus deep overrides. | | labels | Reword or translate any string (defaultLabels lists them). | | feedback | Haptics and sounds, e.g. webVibrationFeedback(). | | reduceMotion | Force motion off or on. By default it follows prefers-reduced-motion. | | components, slotStyles | Replace parts (Button, IntroCard, ResultHero, LeaderboardRow, Countdown, WordDefinition) or add CSS to them. | | pendingStore | window.localStorage: unsent results survive a reload. | | onWordDefinition | ({ gameId, word }) => void when a player opens a Word Search definition. |

GameLauncher props

getSession (preferred) or session, onComplete, onError, onEvent, onClose, autoStart, showLeaderboard, showCountdown, hideChrome, reviewBeforeResult, className, style, and the render overrides renderHeader, renderIntro, renderReview, renderResult, renderSubmitting and renderError. Each override receives the default element, so you can wrap it instead of rebuilding it.

Theming and slots

<SageGameProvider
  theme={createTheme({ brand: '#0ea5e9', mode: 'dark', radius: 'round' })}
  slotStyles={{ button: { borderRadius: 999 }, review: { paddingTop: 8 } }}
  components={{ Button: MyButton, WordDefinition: MyDefinitionDialog }}
  …
/>

Slot style names: button, card, chip, header, intro, resultHero, leaderboardRow, lobbyRow, countdown, gameBoard, review, wordDefinition. For custom game views, the hooks (useQuiz, useMemoryBoard, useSudoku, useWordSearch, useWordRush) and the ui building blocks are exported too.

New in 2.3

• Review before the result. When a game ends, the finished board stays on screen with the score, the time, a key stat and Continue, while the score is verified in the background. It's on by default. Use reviewBeforeResult={false} for the 2.2 flow, and renderReview to customise it. MatchLauncher takes both props too.
• Word Search definitions. Click a found word, in the grid or in the list, to see its definition and note in an accessible dialog (focus is trapped, and Escape closes it). Replace the dialog with the WordDefinition slot.

See CHANGELOG.md (also shipped in this package) for every release.