Docs
useNumberGame

A simple number guessing game implemented as a React hook, allowing users to guess a randomly generated number within a specified range.

Loading...

Installation

pnpm dlx shadcn@latest add https://usekit.kiron.dev/k/use-number-game

Usage

"use client"
 
import { useNumberGame } from "@/hooks/use-number-game"
 
export function Component() {
  const {
    guess,
    message,
    attempts,
    makeGuess,
    resetGame,
    gameOver,
    hasWon,
    hasLost,
    targetNumber,
    history,
    maxAttempts,
  } = useNumberGame({ maxAttempts: 10, revealTarget: false, min: 1, max: 100 })
 
  return (
    <div>
      <h1>Number Guessing Game</h1>
      <p>{message}</p>
      {!gameOver && (
        <form
          onSubmit={(e) => {
            e.preventDefault()
            const value = Number(e.target.elements.guess.value)
            makeGuess(value)
            e.target.reset()
          }}
        >
          <input name="guess" type="number" min={1} max={100} />
          <button
            type="submit"
            style={{
              padding: "8px 16px",
              borderRadius: 4,
              background: "#222",
              color: "#fff",
              border: "none",
              cursor: "pointer",
              marginLeft: 8,
            }}
          >
            Guess
          </button>
        </form>
      )}
      {gameOver && (
        <button
          onClick={resetGame}
          style={{
            padding: "8px 16px",
            borderRadius: 4,
            background: "#e53e3e",
            color: "#fff",
            border: "none",
            cursor: "pointer",
          }}
        >
          Play Again
        </button>
      )}
      <div>
        Attempts: {attempts} / {maxAttempts}
      </div>
      {history.length > 0 && (
        <ul>
          {history.map((entry, i) => (
            <li key={i}>
              {entry.guess}: {entry.label}
            </li>
          ))}
        </ul>
      )}
      {hasWon && <div>🎉 You won!</div>}
      {hasLost && <div>❌ You lost! The number was {targetNumber}.</div>}
    </div>
  )
}

API Reference

Parameters

NameTypeDescriptionDefault ValueOptional
maxAttemptsnumberMaximum number of guesses allowed.10Yes
revealTargetbooleanWhether to reveal the target number during the game.falseYes
minnumberMinimum value for the random number.1Yes
maxnumberMaximum value for the random number.100Yes

Return Values

NameTypeDescription
guessnumber | nullThe last guessed number.
messagestringMessage describing the current game state.
attemptsnumberNumber of attempts made.
makeGuess(guess: number) => voidFunction to make a guess.
resetGame() => voidFunction to reset the game.
gameOverbooleanWhether the game is over.
hasWonbooleanWhether the player has won.
hasLostbooleanWhether the player has lost.
targetNumbernumberThe target number (only if revealTarget is true).
history{ guess: number; label: string }[]Array of previous guesses and their results.
maxAttemptsnumberThe maximum number of attempts allowed.

Notes

  • The hook manages the game state, including attempts, win/loss, and guess history.
  • You can customize the range and number of attempts.
  • Set revealTarget to true to show the target number during the game (useful for debugging or demos).
  • The game resets automatically when the configuration changes.
  • Designed for React and Next.js client components.