🎮 Questro

The most complete gamification library for React with unique visual components

📖 Documentation • � Live Demo • 💬 GitHub

✨ What Makes Questro Unique?

Questro is the only gamification library with battle-tested visual components that create true WOW moments. While other libraries offer basic logic, Questro delivers complete experiences out of the box.

🔥 Exclusive Features (Not Found in Any Other Library)

• 🔥 Combo Meter - Real-time streak tracking with multipliers and timeout visualization
• 🎯 Daily Challenges - 24h reset system with countdown timer and streak tracking
• 🏆 Achievement Toast - Cinematic celebration modals with confetti effects
• ⭕ Progress Rings - Multiple concentric rings with smooth animations

💎 Core Advantages

• 🎯 Complete System - 12 modules covering every gamification need
• ⚡ Zero Dependencies - Pure React, incredibly lightweight (~50KB total)
• 📘 TypeScript First - 100% type-safe with full IntelliSense
• 🎨 Beautiful & Customizable - Stunning defaults, fully customizable
• 🔌 Flexible Storage - LocalStorage, custom API, or any backend
• ⚛️ React Optimized - Built with React best practices and hooks

📦 Installation

npm install questro
# or
yarn add questro
# or
pnpm add questro

⚡ Quick Start

import { PointsProvider, usePoints } from 'questro/points';

function App() {
  return (
    <PointsProvider config={{ userId: 'user-123' }}>
      <Game />
    </PointsProvider>
  );
}

function Game() {
  const { balance, addPoints } = usePoints();

  return (
    <div>
      <h1>Points: {balance}</h1>
      <button onClick={() => addPoints(10, { action: 'complete-task' })}>
        Complete Task (+10)
      </button>
    </div>
  );
}

🔥 Exclusive Visual Components

Combo Meter (Unique to Questro)

Track action streaks with real-time multipliers and timeout visualization.

import { ComboProvider, useCombo, ComboMeter } from 'questro/combo';

function Game() {
  const { combo, multiplier, isActive, addAction } = useCombo();

  return (
    <div>
      <ComboMeter combo={combo} multiplier={multiplier} isActive={isActive} timeRemaining={5000} />
      <button onClick={() => addAction('click')}>Action!</button>
    </div>
  );
}

Daily Challenge (24h Reset System)

Engage users with daily missions that automatically reset.

import {
  DailyChallengeProvider,
  useDailyChallenge,
  DailyChallengeCard,
} from 'questro/daily-challenge';

function Challenges() {
  const { challenge, progress, addProgress } = useDailyChallenge();

  return (
    <DailyChallengeCard
      challenge={challenge}
      progress={progress}
      onAction={() => addProgress(10)}
    />
  );
}

Achievement Toast (Cinematic Celebrations)

Create memorable moments with full-screen achievement celebrations.

import { AchievementToast } from 'questro/achievement-toast';

<AchievementToast
  achievement={{
    title: 'Level Up!',
    description: 'You reached level 10',
    type: 'level',
    icon: '🎉',
    reward: { points: 100, xp: 50 },
    showConfetti: true,
  }}
  onClose={() => {}}
/>;

Progress Rings (Multi-Metric Visualization)

Display multiple progress metrics in beautiful concentric rings.

import { ProgressRings } from 'questro/progress-rings';

<ProgressRings
  rings={[
    { label: 'XP', value: 750, max: 1000, color: '#3b82f6' },
    { label: 'Quests', value: 8, max: 10, color: '#10b981' },
    { label: 'Badges', value: 15, max: 20, color: '#f59e0b' },
  ]}
  size={200}
  centerText="75%"
  centerLabel="Overall"
/>;

🎯 All 12 Modules

Core Gamification

| Module | Description | Key Features | | -------------------- | --------------------- | ---------------------------------------- | | 📊 Points | Point tracking system | Balance, transactions, lifetime total | | 🏆 Badges | Achievement unlocking | Progress tracking, rarity tiers | | 🎯 Quests | Mission system | Multi-objectives, rewards, auto-complete | | 🏅 Leaderboard | Competitive rankings | Real-time updates, user ranks | | ⭐ Levels | XP & leveling system | Level progression, XP curves | | 🔥 Streaks | Daily consistency | Break detection, longest streak | | 🔔 Notifications | Toast system | 4 types, auto-dismiss, queue |

Visual WOW Components (Unique to Questro)

| Module | Description | Why It's Special | | ------------------------ | ------------------ | ----------------------------------------- | | 🔥 Combo Meter | Streak multiplier | Real-time timeout, milestone popups | | 🎯 Daily Challenge | 24h missions | Auto-reset, countdown timer, streak | | 🏆 Achievement Toast | Cinematic modal | Confetti effects, full-screen celebration | | ⭕ Progress Rings | Multi-metric rings | Concentric SVG, smooth animations |

Quick Import Examples

// Points
import { PointsProvider, usePoints } from 'questro/points';
const { balance, addPoints, subtractPoints } = usePoints();

// Badges
import { BadgesProvider, useBadges } from 'questro/badges';
const { badges, updateProgress, unlockBadge } = useBadges();

// Quests
import { QuestsProvider, useQuests } from 'questro/quests';
const { activeQuests, completeQuest } = useQuests();

// Leaderboard
import { LeaderboardProvider, useLeaderboard } from 'questro/leaderboard';
const { entries, updateScore, getUserRank } = useLeaderboard();

// Levels
import { LevelsProvider, useLevels } from 'questro/levels';
const { level, xp, addXP } = useLevels();

// Streaks
import { StreaksProvider, useStreaks } from 'questro/streaks';
const { currentStreak, checkIn } = useStreaks();

// Notifications
import { NotificationsProvider, useNotifications } from 'questro/notifications';
const { show } = useNotifications();

🌟 Perfect For

| Use Case | Modules Used | Results | | --------------------------- | ------------------------------------------------------ | ---------------------------- | | 🎓 E-Learning Platforms | Points, Badges, Levels, Streaks, Daily Challenge | +40% student engagement | | 💪 Fitness Apps | Quests, Combo Meter, Streaks, Achievement Toast | +65% workout completion | | ✅ Productivity Tools | Points, Daily Challenge, Progress Rings, Notifications | +50% daily active users | | 🛒 E-commerce Loyalty | Points, Badges, Leaderboard, Levels | +35% repeat purchases | | 🎮 Social Platforms | All modules | Complete gamification system | | 📚 Reading Apps | Streaks, Badges, Progress Rings, Levels | +55% reading consistency |

Real-World Applications

• Duolingo-style learning apps with streaks and XP
• Strava-like fitness tracking with challenges
• Todoist-style productivity with karma points
• LinkedIn-style profile completion with progress rings
• Fortnite-style battle pass systems with quests

→ View Live Interactive Demo

💾 Flexible Storage

Questro works with any storage backend - from simple localStorage to complex APIs.

Built-in Adapters

import { LocalStorageAdapter, MemoryStorageAdapter } from 'questro';

// Browser localStorage (default)
<PointsProvider storage={new LocalStorageAdapter()} />

// In-memory (for testing or SSR)
<PointsProvider storage={new MemoryStorageAdapter()} />

Custom API Backend

import type { StorageAdapter } from 'questro';

class APIStorage<T> implements StorageAdapter<T> {
  async get(key: string): Promise<T | null> {
    const res = await fetch(`/api/gamification/${key}`);
    return res.ok ? res.json() : null;
  }

  async set(key: string, value: T): Promise<void> {
    await fetch(`/api/gamification/${key}`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(value),
    });
  }
}

// Use your custom storage
<PointsProvider storage={new APIStorage()} />;

Supabase Example

import { createClient } from '@supabase/supabase-js';

class SupabaseStorage<T> implements StorageAdapter<T> {
  private supabase = createClient(url, key);

  async get(key: string): Promise<T | null> {
    const { data } = await this.supabase
      .from('gamification')
      .select('value')
      .eq('key', key)
      .single();
    return data?.value ?? null;
  }

  async set(key: string, value: T): Promise<void> {
    await this.supabase.from('gamification').upsert({ key, value });
  }
}

🔌 Framework Compatibility

| Framework | Support | Notes | | -------------------- | --------------------- | ------------------------- | | React 18+ | ✅ Full | Primary target | | Next.js | ✅ App Router & Pages | Use MemoryStorage for SSR | | Remix | ✅ Full | Works with all loaders | | Vite | ✅ Full | Optimized builds | | Create React App | ✅ Full | Zero config needed | | TypeScript | ✅ 100% | Full type safety |

📊 Bundle Size

Questro is incredibly lightweight with tree-shaking support:

| Module | Size (gzipped) | | --------------------- | -------------- | | Points | ~2 KB | | Badges | ~3 KB | | Quests | ~4 KB | | Leaderboard | ~2.5 KB | | Levels | ~3 KB | | Streaks | ~2.5 KB | | Notifications | ~3.5 KB | | Combo Meter | ~3 KB | | Daily Challenge | ~4 KB | | Achievement Toast | ~2 KB | | Progress Rings | ~1.5 KB | | Full Bundle | ~35 KB |

Import only what you need - unused modules are automatically excluded!

🆚 Comparison with Alternatives

| Feature | Questro | react-rewards | gamify-js | react-game-kit | | --------------------- | -------------- | ------------- | ---------- | -------------- | | Visual Components | ✅ 4 unique | ❌ None | ❌ Basic | ⚠️ Limited | | Combo System | ✅ Full | ❌ | ❌ | ❌ | | Daily Challenges | ✅ Auto-reset | ❌ | ⚠️ Manual | ❌ | | Progress Rings | ✅ Multi-ring | ❌ | ❌ | ❌ | | TypeScript | ✅ 100% | ⚠️ Partial | ❌ | ⚠️ Partial | | Tree Shaking | ✅ Full | ❌ | ❌ | ⚠️ Limited | | Bundle Size | ✅ 35 KB | ~15 KB | ~50 KB | ~45 KB | | Custom Storage | ✅ Any backend | ❌ | ⚠️ Limited | ❌ | | Modules | ✅ 12 | 3 | 5 | 4 |

� Migration Guide

From react-rewards

// Before
import Reward from 'react-rewards';

// After - Much more powerful!
import { AchievementToast } from 'questro/achievement-toast';

From custom solution

Questro handles everything you were building manually:

• ✅ State management → Built-in with persistence
• ✅ Storage → Multiple adapters included
• ✅ TypeScript → Full type safety
• ✅ Visual components → 4 unique components
• ✅ Logic → Battle-tested services

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines.

• � Report bugs
• 💡 Request features
• 🔧 Submit PRs

📄 License

MIT © Gabriel Marques

📖 Documentation • 📦 NPM • 🐛 Issues • 🔧 PRs

Built with ❤️ for the React community

If Questro powers your app, give it a ⭐ on GitHub!

Show Your Support

npm install questro  # Start building amazing gamified experiences! 🎮