react-use-minesweeper

A react custom hook that provides the game logic for Minesweeper.

🔖 Overview

This hook provides the core mechanics for Minesweeper using only standard React APIs. It simplifies the integration of Minesweeper logic into your React applications.

🎮 Demo

You can play example web app here:

🌐 https://mine-sweeper.ebinas.dev/

🚀 API

useMinesweeper hook

Main hook to implement Minesweeper app.
Each method does't depend on state and was defined with useCallback.
(You can optimize rendering with useMemo in your app)

const {
  board,           // The current state of the Minesweeper board.
  gameState,       // The current state of the game (e.g., "initialized", "playing", "completed", "failed").
  gameMode,        // The current game mode (e.g., "easy", "normal", "hard").
  init,            // Function to select game mode & initialize the game.
  restart,         // Function to restart the game in same game mode.
  open,            // Function to open a cell.
  toggleFlag,      // Function to toggle a flag on a cell.
  switchFlagType,  // Function to switch the type of flag(e.g., 🚩, ❓).
  flags,           // The current number of flags used in the game.
  settings         // The game settings constant.
} = useMinesweeper();

Example Implementation

type Props = {
  defaultGameMode: GameMode;
};

const Example: React.FC<Props> = ({ defaultGameMode }) => {
  const {
    board, gameState, gameMode, init, restart, open, toggleFlag, switchFlagType, flags, settings,
  } = useMinesweeper(defaultGameMode);

  return (
    <>
      <h1>Example</h1>
      <p>{`💣: ${board.meta.mines}, 🚩: ${flags.normal}, ❓: ${flags.suspected}`}</p>
      {gameState === 'completed' && <p>🎉 You win!</p>}
      <div>
        {board.data.map((row) => {
          return row.map((cell) => {
            return (
              <Cell key={cell.id} data={cell} open={open} toggleFlag={toggleFlag} switchFlagType={switchFlagType} />
            );
          });
        })}
      </div>
        <div>
            <button onClick={() => init('hard')}>Hard Mode</button>
            <button onClick={restart}>Restart</button>
        </div>
            
    </>
  );
};

Others

| Category | Name | Description | extra | |-------------------|----------------|-------------------------------------------|------------------------------------| | Constants | GAME_MODE_LIST | A list of available game modes. | | | Helper Functions | isMine | Check if a cell is a mine. | | | | isExplodedMine | Check if a cell is a flag. | | | | isMineCount | Check if a cell has a count. | renamed from isCount on v1.0.0 | | | isEmpty | Check if a cell is empty. | | | | isOpened | Check if a cell is opened. | | | | isUnopened | Check if a cell is unopened. | | | | isFlagged | Check if a cell is flagged. (ignore flag type) | | | Types | Minesweeper | Return type of useMinesweeper Hook | | | | GameMode | Type for game modes. | | | | Board | Type for the game board. | | | | BoardConfig | Configuration type for the board. | | | | Cell | Type for individual cell data. | renamed from CellData on v1.0.0 |

📖 Background

This hook is derived from my Next.js application, ebinase/mine-sweeper. Its purpose is to separate the Minesweeper game logic from the UI, enabling easy implementation of Minesweeper in your projects.