react-simple-chessboard

A minimal React chessboard component that uses the popular
chessboard.js library.

react-simple-chessboard is "just a board," meaning that it doesn't provide move
validation, PGN parsing, AI, etc. All it does is show a chessboard with the
pieces in the given position, and optionally let you move pieces around with
drag and drop.

Table of Contents
=================

* Requirements
* Installation
* Importing
* CDN
* Usage
* Controlled component
* Uncontrolled component
* Integration with react-chess.js
* See also
* License

Requirements

* jQuery 1.8.3+
* React 16.8.0+

These are peer dependencies, so you need to install them yourself; they will not
be installed automatically when you install react-simple-chessboard.

Installation

npm install --save react-simple-chessboard

Importing

import Chessboard from 'react-simple-chessboard'; // ES module
const Chessboard = require('react-simple-chessboard'); // CommonJS

$3

If you don't want to import Chessboard into your application, you can load it
from the CDN and use it globally via window.Chessboard:

If you use the CDN, you must load jQuery and React first, e.g.

Usage

There are two ways to use the Chessboard component:

1. As a controlled component, where the state is managed by its parent
2. As an uncontrolled component, where it manages its own state

$3

To use Chessboard as a controlled component, set the position property:

import React, { useState } from 'react';
import Chessboard from 'react-simple-chessboard';

const positions = [
// 1. e4
'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1',
// undo
'start',
// 1. e4
'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1',
// 1. ... c5
'rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR w KQkq c6 0 2',
// 2. Nf3
'rnbqkbnr/pp1ppppp/8/2p5/4P3/5N2/PPPP1PPP/RNBQKB1R b KQkq - 1 2'
];

const App = props => {
const [position, setPosition] = useState('start');

return (

);
};

position should be a string in Forsyth-Edwards
Notation (FEN)
or the string 'start' (the starting position). When the position prop
changes, the board updates to show the new position.

If drag-and-drop is enabled by setting the draggable property to true, you can
use the onChange handler to keep your state variable in sync with the board
position:

import React, { useState } from 'react';
import Chessboard from 'react-simple-chessboard';

const App = props => {
const [position, setPosition] = useState('start');

return (

);
};

$3

To use Chessboard as an uncontrolled component, pass an initial position with
the defaultPosition property:

import React from 'react';
import Chessboard from 'react-simple-chessboard';

const App = props => {
return (

);
};

This simply draws a chessboard in the given position. If drag-and-drop is
enabled by setting the draggable property to true, you can move pieces around
on the board, but you can't access the board's state.

Integration with react-chess.js

You can integrate react-simple-chessboard with
react-chess.js to get move
validation and other features:

import React, { useState } from 'react';
import Chessboard from 'react-simple-chessboard';
import useChess from 'react-chess.js';

const moves = ['e4', 'e5', 'Ba8', 'Nf3'];

const App = (props) => {
const { move, fen, reset, undo } = useChess();

return (

);
};

The third move in this example (Ba8) is illegal, so the board position will not
change the third time you click the "Move" button. See the
react-chess.js documentation
for details.

See also

* react-chess.js: React hook
for integrating with the chess.js library, giving move validation, piece
movement, and callbacks for legal moves, illegal moves, check, checkmate, etc.

* Chessboard.jsx: Another "just a board"
chessboard component for React, but with much more functionality than
react-simple-chessboard, including multiple boards and customizable pieces.
Unfortunately, it is currently unmaintained.

* react-chess: Another React
chessboard component with more features than react-simple-chessboard, but less
than Chessboard.jsx. Also appears unmaintained.

License

react-simple-chessboard is released under the GPLv3 license.