useAchievements

Returns the full achievement engine instance, providing access to all imperative methods like unlock(), setProgress(), reset(), etc.

Signature

function useAchievements<TId extends string>(): AchievementEngine<TId>

Returns

engine

AchievementEngine<TId>

The achievement engine instance with all imperative methods.

Show properties

unlock

(id: TId) => void

Unlock an achievement immediately.

setProgress

(id: TId, value: number) => void

Set the progress value for an achievement. Auto-unlocks when progress reaches maxProgress.

incrementProgress

(id: TId, amount?: number) => void

Increment progress by the specified amount (default: 1). Auto-unlocks when progress reaches maxProgress.

setMaxProgress

(id: TId, max: number) => void

Dynamically set or update the max progress value for an achievement.

reset

() => void

Clear all achievement state and storage.

isUnlocked

(id: TId) => boolean

Check if an achievement is unlocked (non-reactive).

getState

() => AchievementState<TId>

Get the current achievement state snapshot (non-reactive).

getDefinition

(id: TId) => AchievementDef<TId> | undefined

Get the definition for a specific achievement.

dismissToast

(id: TId) => void

Dismiss a toast notification for an achievement.

Subscribe to state changes. Returns an unsubscribe function.

Example

import { useEffect } from "react";
import { useAchievements } from "./achievements";

function SessionInit() {
  const { unlock, isUnlocked } = useAchievements();

  useEffect(() => {
    // Check if this is a returning user
    const isReturning = isUnlocked("first-visit");

    unlock("first-visit");

    if (isReturning) {
      unlock("returning");
    }

    // Check time of day
    if (new Date().getHours() < 5) {
      unlock("night-owl");
    }
  }, [unlock, isUnlocked]);

  return null;
}

import { useAchievements } from "./achievements";

function ClickButton() {
  const { incrementProgress } = useAchievements();

  return (
    <button onClick={() => incrementProgress("click-frenzy")}>
      Click me!
    </button>
  );
}

import { useAchievements } from "./achievements";

function ResetButton() {
  const { reset } = useAchievements();

  return (
    <button onClick={reset}>
      Reset All Achievements
    </button>
  );
}

Notes

This hook does not cause re-renders when state changes - use reactive hooks like useIsUnlocked or useProgress for reactive UI
Must be used within an AchievementsProvider or the factory’s Provider
Use this hook when you need to imperatively trigger achievement actions (unlock, progress updates, etc.)
For reading reactive state, prefer specialized hooks like useIsUnlocked, useProgress, or useUnlockedCount

Core Package

React Package

Signature

Returns

Example

Notes

Build docs developers (and LLMs) love

Core Package

React Package

​Signature

​Returns

​Example

​Notes

Build docs developers (and LLMs) love

Signature

Returns

Example

Notes