react-gameroom

A stateless React component library for multiplayer game lobby management. It handles player slots, room state transitions, QR code generation, and URL routing — you bring your own state management and game logic.

Documentation | Live Demo

Install

npm install react-gameroom

Peer dependencies: react >= 17.0.0 and react-dom >= 17.0.0.

Quick Start

import {
  createInitialRoom, joinPlayer, startGame,
  useRoomState, PlayerSlotsGrid, RoomQRCode, StartGameButton, buildPlayerUrl,
} from "react-gameroom";

// 1. Create a room
const room = createInitialRoom({ minPlayers: 2, maxPlayers: 4, requireFull: false });

// 2. Players join with a name
const updated = joinPlayer(room, 1, "Alice");

// 3. Start the game when conditions are met
const started = startGame(updated);

// 4. Compose the lobby UI from primitives
const { canStart, readyCount } = useRoomState(room);

<RoomQRCode roomId={room.roomId} />
<PlayerSlotsGrid
  players={room.players}
  buildSlotHref={(id) => buildPlayerUrl(room.roomId, id)}
/>
<StartGameButton roomState={room} onStart={updateRoom} />

What's Included

Category	Exports
Components	PlayerSlotsGrid, PlayerSlotView, PlayerScreen, RoomQRCode, JoinGame, RoomInfoModal, StartGameButton
Helpers	createInitialRoom, joinPlayer, startGame, resetPlayer, setPlayerJoining, setPlayerReady, findFirstEmptySlot, deserializeRoom
Hook	useRoomState — derived state with canStart, readyCount, readyPlayers, emptySlots, activePlayers, playerNames
Utils	generateRoomId, buildRoomUrl, buildPlayerUrl, buildJoinUrl, buildRejoinUrl, parseRoomFromUrl

Key Features

• Stateless — helpers take state in, return new state out. You own the state management.
• Headless — components ship with no inline styles. Style via className props and data-status attributes.
• Player identity — optional name and generic data<T> on each slot, carried through transitions.
• Accessible — native <dialog>, aria-live regions, focus trapping, semantic markup.
• Customizable labels — all UI strings are overridable via labels props for i18n and alternative flows.
• Flexible — works with Firebase, Supabase, your own server, or plain useState.

Learn More

• Guide — step-by-step integration walkthrough
• API Reference — types, helpers, hooks, components, utils
• Examples — Rock-Paper-Scissors with Firebase walkthrough
• Live Demo — try it in your browser
• llms.txt — AI-friendly API reference

License

MIT