React Chessboard Component

Common errors

• Error: Cannot find module 'react-chessboard'

  cause The package is not installed or the import path is incorrect, or a CommonJS environment is trying to `require` an ESM-only package.
  fix Install the package: `npm install react-chessboard` (or `pnpm add react-chessboard`, `yarn add react-chessboard`). Ensure you are using `import { Chessboard } from 'react-chessboard';` in an ESM-compatible environment or build setup.

• Warning: Peer dependency 'react@^19.0.0' not installed.

  cause Your project's `react` version does not satisfy the `react-chessboard` peer dependency requirement.
  fix Update your `react` and `react-dom` packages to version `19.0.0` or newer: `npm install react@^19.0.0 react-dom@^19.0.0`.

• Invariant Violation: Hydration failed because the initial UI does not match what was rendered on the server.

  cause Typically occurs in Next.js or similar SSR frameworks when a component that relies on client-side browser APIs (like `react-chessboard` for drag-and-drop) is rendered on the server without proper client-side directives.
  fix Add `'use client';` at the top of the file where `Chessboard` is rendered, or use `next/dynamic` to import `Chessboard` with `ssr: false`.

Warnings

• breaking Version 5.x and above requires React 19.0.0 as a peer dependency. Applications using older React versions (e.g., React 18) must upgrade their React installation to use the latest `react-chessboard` features.
  Fix: Upgrade your project's `react` and `react-dom` dependencies to `^19.0.0` or higher. For example: `npm install react@^19.0.0 react-dom@^19.0.0`.
• gotcha When using `react-chessboard` within Next.js or other server-side rendering (SSR) frameworks, the component must be rendered on the client side. Failing to do so can lead to hydration mismatches or errors.
  Fix: Ensure the component consuming `Chessboard` includes `'use client';` at the top of the file, or dynamically import the component using `next/dynamic` with `ssr: false`.
• gotcha The `engines` field in `package.json` specifies minimum Node.js (>=20.11.0) and pnpm (>=9.4.0) versions. Using older versions may lead to installation or runtime issues.
  Fix: Ensure your development environment meets the specified engine requirements. Update Node.js to `v20.11.0` or newer, and pnpm to `v9.4.0` or newer.
• gotcha Prior to v5.9.1, the `onClick` handler could unexpectedly fire on mobile devices when attempting to drop pieces, leading to unintended moves or UI behavior.
  Fix: Upgrade to `react-chessboard@5.9.1` or newer to resolve the issue with `onClick` firing incorrectly during mobile piece drops.

Install

• npm install react-chessboard npm
• yarn add react-chessboard yarn
• pnpm add react-chessboard pnpm

Imports

• Chessboard
  wrong:

  const Chessboard = require('react-chessboard');

  correct:

  import { Chessboard } from 'react-chessboard';

  The primary component for rendering a chessboard. The library is ESM-first.
• ChessboardProps

  import type { ChessboardProps } from 'react-chessboard';

  Type definition for the props accepted by the Chessboard component, useful for TypeScript projects.
• SquareRenderer

  import type { SquareRenderer } from 'react-chessboard';

  Type alias for custom square rendering functions, exposed since v5.9.0 for advanced customization.

Quickstart

Demonstrates basic setup of the Chessboard component, integrating with `chess.js` for game logic to handle piece drops, update the game state, and display the FEN.

import { useState, useCallback } from 'react';
import { Chessboard } from 'react-chessboard';
import { Chess } from 'chess.js'; // Often used for game logic

function App() {
  const [game, setGame] = useState(new Chess());

  const onDrop = useCallback((sourceSquare: string, targetSquare: string) => {
    try {
      const move = game.move({
        from: sourceSquare,
        to: targetSquare,
        promotion: 'q' // For simplicity, always promote to queen
      });
      if (move === null) return false; // Illegal move
      setGame(new Chess(game.fen())); // Update state to trigger re-render
      return true; // Valid move
    } catch (e) {
      console.error("Error making move:", e);
      return false; // Error (e.g., illegal move)
    }
  }, [game]);

  return (
    <div style={{ maxWidth: '400px', margin: 'auto', padding: '20px' }}>
      <h1>React Chessboard Simple Game</h1>
      <Chessboard position={game.fen()} onPieceDrop={onDrop} />
      <p style={{ marginTop: '10px' }}>Current FEN: {game.fen()}</p>
      <button style={{ marginTop: '10px' }} onClick={() => setGame(new Chess())}>Reset Game</button>
    </div>
  );
}

export default App;