React Achievements

Add gamification to your React app in 5 minutes - Unlock achievements, celebrate milestones, delight users.

📚 Documentation | 🎮 Interactive Demo | 📦 npm Package

Installation

npm install react-achievements

Requirements: React 17.0+, Node.js 16+

Usage

React Achievements supports two tracking patterns:

Pattern 1: Event-Based Tracking

Track achievements using semantic events. Perfect for complex applications or multi-framework projects.

// achievementEngine.ts
import { AchievementEngine } from 'react-achievements';

const achievements = {
  score: {
    100: { title: 'Century!', description: 'Score 100 points', icon: '🏆' },
  }
};

const eventMapping = {
  'userScored': (data) => ({ score: data.points }),
};

export const engine = new AchievementEngine({
  achievements,
  eventMapping,
  storage: 'local'
});

// App.tsx
import { AchievementProvider } from 'react-achievements';
import { engine } from './achievementEngine';

function App() {
  return (
    <AchievementProvider engine={engine} useBuiltInUI={true}>
      <Game />
    </AchievementProvider>
  );
}

// Game.tsx
import { useAchievementEngine } from 'react-achievements';

function Game() {
  const engine = useAchievementEngine();
  
  return (
    <button onClick={() => engine.emit('userScored', { points: 100 })}>
      Score Points
    </button>
  );
}

➡️ Event-Based Tracking Guide

Pattern 2: Direct Track Updates

Update metrics directly in your React components. Perfect for simple applications or quick prototypes.

// achievements.ts
const achievements = {
  score: {
    100: { title: 'Century!', description: 'Score 100 points', icon: '🏆' },
  }
};

// App.tsx
import { AchievementProvider } from 'react-achievements';

function App() {
  return (
    <AchievementProvider achievements={achievements} useBuiltInUI={true}>
      <Game />
    </AchievementProvider>
  );
}

// Game.tsx
import { useSimpleAchievements, BadgesButtonWithModal } from 'react-achievements';

function Game() {
  const { track, unlocked } = useSimpleAchievements();

  return (
    <div>
      <button onClick={() => track('score', 100)}>Score Points</button>
      <BadgesButtonWithModal unlockedAchievements={unlocked} />
    </div>
  );
}

➡️ Direct Updates Guide

Documentation

📚 Full Documentation - Complete guides, API reference, and examples

License

React Achievements is dual-licensed:

• Free for Non-Commercial Use (MIT License) - Personal projects, education, non-profits, open source
• Commercial License Required - Businesses, SaaS, commercial apps, enterprise

Get Commercial License → | License Details | Commercial Terms

Built with ❤️ by Dave B | 📚 Documentation | ⭐ Star on GitHub