Registry / web-framework / react-chessboard

react-chessboard

library5.10.0jsnpmunverified

React Chessboard is a modern, responsive, and accessible chessboard component for React applications, currently at stable version 5.10.0. It provides core functionality for rendering chessboards with drag-and-drop piece movement, custom piece rendering, animation, and comprehensive event handling. The library maintains a continuous release cadence, with frequent minor updates and bug fixes, often several times a month. Key differentiators include robust mobile support, built-in responsiveness, accessibility features, and full TypeScript support, ensuring type safety and improved developer experience. It requires React 19.0.0 as a peer dependency, aligning with the latest React ecosystem, making it suitable for modern React projects and providing a flexible foundation for building various chess-related user interfaces.

web-framework

npm install react-chessboard

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-CHESSBOARD

react-chessboard

web-frameworkjavascriptv5.10.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Chessboard

✓ import { Chessboard } from 'react-chessboard';

✗ const Chessboard = require('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.

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;

Debug

Known issues

breakingVersion 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`.

affects: >=5.0.0

gotchaWhen 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`.

affects: >=1.0.0

gotchaThe `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.

affects: >=5.x

gotchaPrior 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.

affects: <5.9.1

Errors

Common errors & fixes

Error: Cannot find module 'react-chessboard'

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.

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.

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`.

Upgrade

Version history

5.10.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency for the React component.

react-domrequiredPeer dependency for rendering React components.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/Clariity/react-chessboard ↗

packagehttps://www.npmjs.com/package/react-chessboard ↗

homepagehttps://chessboard.xyz ↗