react-achievements-zustand

# 🏆 React-Achievements-Zustand A flexible achievement system for React applications using Zustand for state management. ![React Achievements Demo](https://media.giphy.com/media/5sXoITml136LmyBPEc/giphy.gif) Try it out: [StackBlitz Demo](https://stackblitz.com/edit/vitejs-vite-rymmutrx) ## Quick Start ```bash npm install react react-dom zustand react-achievements-zustand ``` ```jsx import { AchievementProvider, useAchievement } from 'react-achievements-zustand'; // 1. Define achievements const achievementConfig = { score: [{ isConditionMet: (value) => value >= 100, achievementDetails: { achievementId: 'high-score', achievementTitle: 'High Score!', achievementDescription: 'Score 100 points', achievementIconKey: 'trophy' } }] }; // 2. Use the provider function App() { return ( <AchievementProvider config={achievementConfig}> <Game /> </AchievementProvider> ); } // 3. Update metrics function Game() { const { updateMetrics } = useAchievement(); const handleScore = () => { updateMetrics({ score: [100] // Values are always passed in arrays }); }; return <button onClick={handleScore}>Score Points</button>; } ``` ## Core Features ### Metric Updates ```jsx const { updateMetrics } = useAchievement(); // Single update updateMetrics({ score: [100] }); // Multiple metrics updateMetrics({ score: [100], combo: [5], time: [60] }); // Sequential updates updateMetrics({ score: [50] }); setTimeout(() => updateMetrics({ score: [100] }), 1000); ``` ### Achievement Notifications - Powered by react-toastify - Shows multiple achievements simultaneously - Customizable appearance ```css /* Custom notification styling */ .Toastify__toast { background-color: #2c3e50; color: #ecf0f1; border-radius: 10px; } ``` ### State Management ```jsx // Save progress const { metrics, previouslyAwardedAchievements } = useAchievementState(); // Load progress <AchievementProvider config={achievementConfig} initialState={{ metrics: savedMetrics, previouslyAwardedAchievements: savedAchievements }} /> ``` ### Reset Progress ```jsx const { resetStorage } = useAchievement(); resetStorage(); // Clears all progress ``` ## Available Icons ### Achievement Types - 🏆 `trophy` - Classic achievement symbol - ⭐ `star` - General achievement - 🥉 `bronze` - Bronze tier achievement - 🥈 `silver` - Silver tier achievement - 🥇 `gold` - Gold tier achievement - 💎 `diamond` - Diamond tier achievement - ✨ `legendary` - Legendary achievement - 💥 `epic` - Epic achievement - 🔮 `rare` - Rare achievement - 🔘 `common` - Common achievement - 🎁 `special` - Special achievement ### Progress & Milestones - 📈 `growth` - Progress indicator - 🔥 `streak` - Streak achievements - 👑 `master` - Mastery achievements - 🚀 `pioneer` - Pioneer or early adopter - 💡 `breakthrough` - Discovery or breakthrough - 🌱 `newBeginnings` - First-time achievements - 👣 `firstStep` - First achievement - 🏅 `milestoneReached` - Milestone completion - 🏁 `challengeCompleted` - Challenge completion ### Social & Engagement - 🔗 `shared` - Sharing achievement - ❤️ `liked` - Appreciation - 💬 `commented` - Communication - 👥 `followed` - Following achievement - 🤝 `invited` - Invitation achievement - 🏘️ `communityMember` - Community participation - 🌟 `supporter` - Support achievement - 🌐 `connected` - Connection achievement - 🙋 `participant` - Participation - 📣 `influencer` - Influence achievement ### Time & Activity - ☀️ `activeDay` - Daily activity - 📅 `activeWeek` - Weekly activity - 🗓️ `activeMonth` - Monthly activity - ⏰ `earlyBird` - Early participation - 🌙 `nightOwl` - Late participation - ⏳ `dedicated` - Time dedication - ⏱️ `punctual` - Timeliness - 🔄 `consistent` - Consistency - 🏃 `marathon` - Long-term achievement ### Creativity & Expertise - 🎨 `artist` - Artistic achievement - ✍️ `writer` - Writing achievement - 🔬 `innovator` - Innovation - 🛠️ `creator` - Creation achievement - 🎓 `expert` - Expertise achievement - 🎭 `performer` - Performance achievement - 🧠 `thinker` - Thinking achievement - 🗺️ `explorer` - Exploration achievement ### Action & Interaction - 🖱️ `clicked` - Click interaction - 🔑 `used` - Usage achievement - 🔍 `found` - Discovery achievement - 🧱 `built` - Building achievement - 🧩 `solved` - Problem solving - 🔭 `discovered` - Discovery - 🔓 `unlocked` - Unlocking achievement - ⬆️ `upgraded` - Upgrade achievement - 🔧 `repaired` - Fix achievement - 🛡️ `defended` - Defense achievement ### Numbers & Counters - 1️⃣ `one` - First achievement - 🔟 `ten` - Tenth achievement - 💯 `hundred` - Hundredth achievement - 🔢 `thousand` - Thousandth achievement ### System Icons - ⭐ `default` - Default fallback icon - ⏳ `loading` - Loading state - ⚠️ `error` - Error state - ✅ `success` - Success state - ❌ `failure` - Failure state ### Additional Decorative Icons - 🚩 `flag` - Flag marker - 💎 `gem` - Gem reward - 🎗️ `ribbon` - Ribbon award - 🎖️ `badge` - Badge award - ⚔️ `monsterDefeated` - Combat achievement - 📦 `itemCollected` - Collection achievement ### Usage Example ```jsx const achievementConfig = { score: [{ isConditionMet: (value) => value >= 100, achievementDetails: { achievementId: 'high-score', achievementTitle: 'High Score!', achievementDescription: 'Score 100 points', achievementIconKey: 'legendary' // Use any icon key from above } }] }; ``` ## Advanced Features ### Custom Styling ```jsx const styles = { badgesButton: { position: 'fixed', top: '20px', right: '20px', // ...more styles }, badgesModal: { overlay: { backgroundColor: 'rgba(0,0,0,0.8)' }, // ...more styles } }; <AchievementProvider styles={styles}> <App /> </AchievementProvider> ``` ### Persistence ```jsx <AchievementProvider config={achievementConfig} storageKey="my-game-achievements" // localStorage key initialState={loadedState} /> ``` ## Complete Documentation - [Full Example](#full-example) - [API Reference](#api-reference) - [Icon List](#full-icon-list) - [Styling Guide](#styling-guide) - [Migration Guide](#migration-guide)