{"id":11661,"library":"react-chessboard","title":"React Chessboard Component","description":"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.","status":"active","version":"5.10.0","language":"javascript","source_language":"en","source_url":"https://github.com/Clariity/react-chessboard","tags":["javascript","typescript"],"install":[{"cmd":"npm install react-chessboard","lang":"bash","label":"npm"},{"cmd":"yarn add react-chessboard","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-chessboard","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the React component.","package":"react","optional":false},{"reason":"Peer dependency for rendering React components.","package":"react-dom","optional":false}],"imports":[{"note":"The primary component for rendering a chessboard. The library is ESM-first.","wrong":"const Chessboard = require('react-chessboard');","symbol":"Chessboard","correct":"import { Chessboard } from 'react-chessboard';"},{"note":"Type definition for the props accepted by the Chessboard component, useful for TypeScript projects.","symbol":"ChessboardProps","correct":"import type { ChessboardProps } from 'react-chessboard';"},{"note":"Type alias for custom square rendering functions, exposed since v5.9.0 for advanced customization.","symbol":"SquareRenderer","correct":"import type { SquareRenderer } from 'react-chessboard';"}],"quickstart":{"code":"import { useState, useCallback } from 'react';\nimport { Chessboard } from 'react-chessboard';\nimport { Chess } from 'chess.js'; // Often used for game logic\n\nfunction App() {\n const [game, setGame] = useState(new Chess());\n\n const onDrop = useCallback((sourceSquare: string, targetSquare: string) => {\n try {\n const move = game.move({\n from: sourceSquare,\n to: targetSquare,\n promotion: 'q' // For simplicity, always promote to queen\n });\n if (move === null) return false; // Illegal move\n setGame(new Chess(game.fen())); // Update state to trigger re-render\n return true; // Valid move\n } catch (e) {\n console.error(\"Error making move:\", e);\n return false; // Error (e.g., illegal move)\n }\n }, [game]);\n\n return (\n
\n

React Chessboard Simple Game

\n \n

Current FEN: {game.fen()}

\n \n
\n );\n}\n\nexport default App;","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.x"},{"fix":"Upgrade to `react-chessboard@5.9.1` or newer to resolve the issue with `onClick` firing incorrectly during mobile piece drops.","message":"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.","severity":"gotcha","affected_versions":"<5.9.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The package is not installed or the import path is incorrect, or a CommonJS environment is trying to `require` an ESM-only package.","error":"Error: Cannot find module 'react-chessboard'"},{"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`.","cause":"Your project's `react` version does not satisfy the `react-chessboard` peer dependency requirement.","error":"Warning: Peer dependency 'react@^19.0.0' not installed."},{"fix":"Add `'use client';` at the top of the file where `Chessboard` is rendered, or use `next/dynamic` to import `Chessboard` with `ssr: false`.","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.","error":"Invariant Violation: Hydration failed because the initial UI does not match what was rendered on the server."}],"ecosystem":"npm"}