react-chess.js

React hook for the chess.js library.

react-chess.js provides a custom React hook, useChess, that makes it easier to integrate the popular chess.js library into your React app. chess.js provides move validation, PGN import/export, piece movement, and check/checkmate/stalemate/draw detection, but no chessboard (for that see chessboardjsx, for example).

react-chess.js hides most of the imperative code in chess.js so you can focus on building declarative React components. Currently it only exposes a portion of the chess.js API, including:

• piece movement
• move validation
• callbacks for check, checkmate, draw, stalemate, threefold repetition, insufficient material, and game over
• board position in FEN notation

The rest of the API will be added in future releases.

Installation

npm install --save react-chess.js

React 16.8.0+ is a peer dependency, so you must install it yourself.

Importing

import useChess from 'react-chess.js'; // ES module
const useChess = require('react-chess.js'); // CommonJS

CDN

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

<script src="https://unpkg.com/react-chess.js"></script>

Usage

The following example shows some of the features of the useChess hook:

import React from 'react';
import useChess from 'react-chess.js';

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

const App = (props) => {
    const { move, history, fen, reset, undo, turn } = useChess({
        onLegalMove: moved => console.log(`Made move: ${moved}`),
        onIllegalMove: moved => console.log(`Illegal move: ${moved}`),
        onGameOver: () => console.log('Game over')
    });

    return (
        <div className="app">
            <h1>{turn === 'b' ? 'Black' : 'White'} to move</h1>

            <button onClick={() => move(moves.shift())}>Move</button>
            <button onClick={undo}>Undo</button>
            <button onClick={reset}>Reset</button>

            <h1>Board position:</h1>
            <p>{fen}</p>

            <h1>Move history:</h1>
            <ol>
              {history.map((moveText, i) => (<li key={i}>{moveText}</li>))}
            </ol>
        </div>
    );
};

Each time you click the "Move" button, a move will be attempted, in the order e4, e5, Ba8, and Nf3. When a move is made, a message is logged to the console indicating whether it was legal or illegal. The current board position in Forsyth-Edwards notation, the player whose turn it is, and the list of moves made so far are shown and updated automatically after each move. Clicking "Undo" undoes the last move, while clicking "Reset" resets the board to the starting position.

Arguments

useChess takes an optional configuration object as an argument. This lets you pass callbacks that are triggered on certain game events, like checkmate.

Note that multiple callbacks may be triggered by the same move. For example, if you define onLegalMove, onDraw, and onGameOver and the game ends in a draw, all three callbacks will be fired after the last legal move in the game.

The following callbacks are supported:

onLegalMove

function(move) optional

Called after a legal move has been made. The function is called with one argument: the move that was made, expressed in standard algebraic notation (e.g. 'Nf3').

If the move puts the other player in check or checkmate, move will include '+' or '#', even if it was not included when the move was made. For example:

const handleLegalMove = moveMade => console.log(moveMade);
const { move } = useChess({ onLegalMove: handleLegalMove });

move('e4');
move('e5');
move('Qf3');
move('Nc6');
move('Qxf7'); // calls handleLegalMove('Qxf7+')

onIllegalMove

function(move) optional

Called when an illegal or ambiguous move is attempted. The function is called with one argument: the move that was attempted, expressed in standard algebraic notation (e.g. 'Naxh1').

onGameOver

function() optional

Called when the game is over due to checkmate, stalemate, or a draw.

onCheck

function() optional

Called when a move puts the next player in check.

onCheckmate

function() optional

Called when a move puts the next player in checkmate.

onDraw

function() optional

Called when the game is drawn due to the 50-move rule or insufficient material.

onStalemate

function() optional

Called when a move puts the next player in stalemate.

onThreefoldRepetition

function() optional

Called when the current board position has ocurred three or more times.

onInsufficientMaterial

function() optional

Called when the game is drawn due to insufficient material (e.g. king vs king).

Returns

useChess returns an object with the following properties:

move

function(move)

Make the given move. move should be expressed in standard algebraic notation (e.g. 'Kh1').

reset

function reset()

Reset the game to the beginning.

undo

function undo()

Undo the last move.

history

Array

An array containing the moves that have been made so far in the game, in standard algebraic notation.

fen

String

The current position of the pieces in FEN notation.

turn

String

The player whose turn it is (either 'b' for black or 'w' for white).

License

react-chess.js is released under the GPLv3 license.