@playpulse/react

React UI components for PlayPulse Gamification Framework.

Installation

npm install @playpulse/react @playpulse/sdk
# or
pnpm add @playpulse/react @playpulse/sdk
# or
yarn add @playpulse/react @playpulse/sdk

Quick Start

import { PlayPulseProvider, usePlayer } from '@playpulse/sdk/react'
import { ThemeProvider, PlayerHeader, QuestList, Leaderboard } from '@playpulse/react'

function App() {
  return (
    <PlayPulseProvider
      config={{
        apiKey: 'pp_live_xxx',
        projectId: 'your-project-id',
      }}
    >
      <ThemeProvider theme={{ colors: { primary: '#6366f1' } }}>
        <GameUI />
      </ThemeProvider>
    </PlayPulseProvider>
  )
}

function GameUI() {
  const { identify } = usePlayer()

  useEffect(() => {
    identify('user-123')
  }, [])

  return (
    <div className="space-y-4">
      <PlayerHeader />
      <QuestList />
      <Leaderboard leaderboardId="main-leaderboard" />
    </div>
  )
}

Components

PlayerHeader

Displays player avatar, name, level, XP, lives, and currencies.

<PlayerHeader
  showLevel={true}
  showXp={true}
  showLives={true}
  showCurrencies={['coins', 'gems']}
  compact={false}
/>

QuestList

Shows available and in-progress quests with progress tracking.

<QuestList
  showAvailable={true}
  showInProgress={true}
  showCompleted={false}
  maxItems={10}
  onStartQuest={(questId) => console.log('Started', questId)}
/>

AdventureOverview

Displays adventure/season progress with quest checklist.

<AdventureOverview
  adventureId="current-season"
  showQuests={true}
/>

Leaderboard

Shows rankings with player position.

<Leaderboard
  leaderboardId="weekly-xp"
  limit={10}
  showPlayerRank={true}
  subscribe={true}
/>

Lobby

Multiplayer lobby with ready status and player management.

<Lobby
  lobbyId="game-123"
  subscribe={true}
  onStart={() => console.log('Game started!')}
/>

Chat

Real-time chat with message history.

<Chat
  channelId="lobby-chat"
  subscribe={true}
  maxHeight={400}
  showTimestamps={true}
/>

Theming

Customize the look and feel with CSS variables:

<ThemeProvider
  theme={{
    colors: {
      primary: '#6366f1',
      success: '#22c55e',
      warning: '#f59e0b',
      danger: '#ef4444',
    },
    radius: '0.75rem',
    fontFamily: 'Inter, sans-serif',
  }}
>
  {children}
</ThemeProvider>

Or use CSS variables directly:

:root {
  --pp-primary-500: #6366f1;
  --pp-radius: 0.75rem;
  --pp-font-sans: 'Inter', sans-serif;
}

Styling

Components use Tailwind CSS with the pp- prefix to avoid conflicts. Import the base styles:

import '@playpulse/react/styles.css'

License

MIT