chess.js

chess.js is a TypeScript chess library used for chess move generation/validation, piece placement/movement, and check/checkmate/stalemate detection - basically everything but the AI.

chess.js has been extensively tested in node.js and most modern browsers.

Installation

Run the following command to install the most recent version of chess.js from NPM:

npm install chess.js

Importing

Import (as ESM)

import { Chess } from 'chess.js'

ECMAScript modules (ESM) can be directly imported in a browser:

<script type="module">
  import { Chess } from 'chess.js'
</script>

Import (as CommonJS)

const { Chess } = require('chess.js')

Example Code

The code below plays a random game of chess:

import { Chess } from 'chess.js'

const chess = new Chess()

while (!chess.isGameOver()) {
  const moves = chess.moves()
  const move = moves[Math.floor(Math.random() * moves.length)]
  chess.move(move)
}
console.log(chess.pgn())

User Interface

By design, chess.js is a headless library and does not include user interface elements. Many developers have successfully integrated chess.js with the chessboard.js library. See chessboard.js - Random vs Random for an example.

Parsers (permissive / strict)

This library includes two parsers (permissive and strict) which are used to parse different forms of chess move notation. The permissive parser (the default) is able to handle many non-standard derivatives of algebraic notation (e.g. Nf3, g1f3, g1-f3, Ng1f3, Ng1-f3, Ng1xf3). The strict parser only accepts moves in Standard Algebraic Notation and requires that they strictly adhere to the specification. The strict parser runs slightly faster but will not parse any non-standard notation.

API

Constants

The following constants are exported from the top-level module:

// colors
export const WHITE = 'w'
export const BLACK = 'b'

// pieces
export const PAWN = 'p'
export const KNIGHT = 'n'
export const BISHOP = 'b'
export const ROOK = 'r'
export const QUEEN = 'q'
export const KING = 'k'

// starting position (in FEN)
export const DEFAULT_POSITION = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'

// square list
export const SQUARES = ['a8', 'b8', 'c8', ..., 'f1', 'g1', 'h1']

Constructor: Chess([ fen ], { skipValidation = false } = {})

The Chess() constructor creates a new chess object that default to the initial board position. It accepts two optional parameters : a string which specifies the board configuration in Forsyth-Edwards Notation (FEN), and an object with a skipValidation boolean. By default the constructor will throw an exception if an invalid FEN string is provided. This behavior can be skipped by setting the skipValidation boolean.

import { Chess } from 'chess.js'

// an empty constructor defaults the starting position
let chess = new Chess()

// pass in a FEN string to load a particular position
let chess = new Chess(
  'r1k4r/p2nb1p1/2b4p/1p1n1p2/2PP4/3Q1NB1/1P3PPP/R5K1 b - - 0 19',
)

// the white king is missing from the FEN string below
let chess = new Chess(
  'r1k4r/p2nb1p1/2b4p/1p1n1p2/2PP4/3Q1NB1/1P3PPP/R52 b - - 0 19',
  { skipValidation = true },
)

.ascii()

Returns a string containing an ASCII diagram of the current position.

const chess = new Chess()

// make some moves
chess.move('e4')
chess.move('e5')
chess.move('f4')

chess.ascii()
// -> '   +------------------------+
//      8 | r  n  b  q  k  b  n  r |
//      7 | p  p  p  p  .  p  p  p |
//      6 | .  .  .  .  .  .  .  . |
//      5 | .  .  .  .  p  .  .  . |
//      4 | .  .  .  .  P  P  .  . |
//      3 | .  .  .  .  .  .  .  . |
//      2 | P  P  P  P  .  .  P  P |
//      1 | R  N  B  Q  K  B  N  R |
//        +------------------------+
//          a  b  c  d  e  f  g  h'

.attackers(square, [ color ])

Returns a list of squares that have pieces belonging to the side to move that can attack the given square. This function takes an optional parameter which can change which color the pieces should belong to.

const chess = new Chess()

chess.attackers('f3')
// -> ['e2', 'g2', 'g1'] (empty squares can be attacked)

chess.attackers('e2')
// -> ['d1', 'e1', 'f1', 'g1'] (we can attack our own pieces)

chess.attackers('f6')
// -> [] (squares not attacked by the side to move will return an empty list)

chess.move('e4')
chess.attackers('f6')
// -> ['g8', 'e7', 'g7'] (return value changes depending on side to move)

chess.attackers('f3', WHITE)
// -> ['g2', 'd1', 'g1'] (side to move can be ignored by specifying a color)

chess.load('4k3/4n3/8/8/8/8/4R3/4K3 w - - 0 1')
chess.attackers('c6', BLACK)
// -> ['e7'] (pieces still attack a square even if they are pinned)

.board()

Returns a 2D array representation of the current position. Empty squares are represented by null.

const chess = new Chess()

chess.board()
// -> [[{square: 'a8', type: 'r', color: 'b'},
//      {square: 'b8', type: 'n', color: 'b'},
//      {square: 'c8', type: 'b', color: 'b'},
//      {square: 'd8', type: 'q', color: 'b'},
//      {square: 'e8', type: 'k', color: 'b'},
//      {square: 'f8', type: 'b', color: 'b'},
//      {square: 'g8', type: 'n', color: 'b'},
//      {square: 'h8', type: 'r', color: 'b'}],
//      [...],
//      [...],
//      [...],
//      [...],
//      [...],
//      [{square: 'a1', type: 'r', color: 'w'},
//       {square: 'b1', type: 'n', color: 'w'},
//       {square: 'c1', type: 'b', color: 'w'},
//       {square: 'd1', type: 'q', color: 'w'},
//       {square: 'e1', type: 'k', color: 'w'},
//       {square: 'f1', type: 'b', color: 'w'},
//       {square: 'g1', type: 'n', color: 'w'},
//       {square: 'h1', type: 'r', color: 'w'}]]

.clear({ preserveHeaders = false } = {})

Clears the board.

chess.clear()
chess.fen()
// -> '8/8/8/8/8/8/8/8 w - - 0 1' <- empty board

.fen({ forceEnpassantSquare = false) = {})

Returns the FEN string for the current position. Note, the en passant square is only included if the side-to-move can legally capture en passant.

The enpassant square will always be included if forceEnpassantSquare is true.

const chess = new Chess()

// make some moves
chess.move('e4')
chess.move('e5')
chess.move('f4')

chess.fen()
// -> 'rnbqkbnr/pppp1ppp/8/4p3/4PP2/8/PPPP2PP/RNBQKBNR b KQkq - 0 2'

.findPiece(piece)

Returns a list containing the squares where the requested piece is located. Returns an empty list if the piece is not on the board.

const chess = new Chess()

chess.findPiece({ type: KING, color: BLACK })
// -> ['e8']
chess.findPiece({ type: BISHOP, color: WHITE })
// -> ['c1', 'f1']
chess.remove('d1')
chess.findPiece({ type: QUEEN, color: WHITE })
// -> []

.get(square)

Returns the piece on the square. Returns undefined if the square is empty.

chess.put({ type: PAWN, color: BLACK }, 'a5') // put a black pawn on a5

chess.get('a5')
// -> { type: 'p', color: 'b' },
chess.get('a6')
// -> undefined

.getCastlingRights(color)

Gets the castling rights for the given color. An object is returned which indicates whether the right is available or not for both kingside and queenside. Note this does not indicate if such a move is legal or not in the current position as checks etc. also need to be considered.

const chess = new Chess()

chess.getCastlingRights(BLACK) // black can castle queenside only
// -> { 'k': false, 'q': true }

.getComment()

Retrieve the comment for the current position, if it exists.

const chess = new Chess()

chess.loadPgn('1. e4 e5 2. Nf3 Nc6 3. Bc4 Bc5 {giuoco piano} *')

chess.getComment()
// -> "giuoco piano"

.getComments()

Retrieve comments for all positions.

const chess = new Chess()

chess.loadPgn(
  "1. e4 e5 {king's pawn opening} 2. Nf3 Nc6 3. Bc4 Bc5 {giuoco piano} *",
)

chess.getComments()
// -> [
//     {
//       fen: "rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2",
//       comment: "king's pawn opening"
//     },
//     {
//       fen: "r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3",
//       comment: "giuoco piano"
//     }
//    ]

.getHeaders()

Retrieve the PGN headers.

chess.setHeader('White', 'Morphy')
chess.setHeader('Black', 'Anderssen')
chess.setHeader('Date', '1858-??-??')
chess.getHeaders()
// -> { White: 'Morphy', Black: 'Anderssen', Date: '1858-??-??' }

.hash()

Returns a unique 64-bit hash as a hexidecimal string for the current position.

chess.hash()
// -> '3436f01fd716346e'

.history([ options ])

Returns a list containing the moves of the current game. Options is an optional parameter which may contain a 'verbose' flag. See .moves() for a description of the verbose move fields. A FEN string of the position prior to the move being made is added to the verbose history output.

const chess = new Chess()
chess.move('e4')
chess.move('e5')
chess.move('f4')
chess.move('exf4')

chess.history()
// -> ['e4', 'e5', 'f4', 'exf4']

chess.history({ verbose: true })
// -->
// [
//   {
//     before: 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1',
//     after: 'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1',
//     color: 'w',
//     piece: 'p',
//     from: 'e2',
//     to: 'e4',
//     san: 'e4',
//     lan: 'e2e4',
//   },
//   {
//     before: 'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1',
//     after: 'rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2',
//     color: 'b',
//     piece: 'p',
//     from: 'e7',
//     to: 'e5',
//     san: 'e5',
//     lan: 'e7e5',
//   },
//   {
//     before: 'rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2',
//     after: 'rnbqkbnr/pppp1ppp/8/4p3/4PP2/8/PPPP2PP/RNBQKBNR b KQkq - 0 2',
//     color: 'w',
//     piece: 'p',
//     from: 'f2',
//     to: 'f4',
//     san: 'f4',
//     lan: 'f2f4',
//   },
//   {
//     before: 'rnbqkbnr/pppp1ppp/8/4p3/4PP2/8/PPPP2PP/RNBQKBNR b KQkq - 0 2',
//     after: 'rnbqkbnr/pppp1ppp/8/8/4Pp2/8/PPPP2PP/RNBQKBNR w KQkq - 0 3',
//     color: 'b',
//     piece: 'p',
//     from: 'e5',
//     to: 'f4',
//     san: 'exf4',
//     lan: 'e5f4',
//     captured: 'p'
//   }
// ]

.inCheck()

Returns true or false if the side to move is in check.

const chess = new Chess(
  'rnb1kbnr/pppp1ppp/8/4p3/5PPq/8/PPPPP2P/RNBQKBNR w KQkq - 1 3',
)
chess.inCheck()
// -> true

.isAttacked(square, color)

Returns true if the square is attacked by any piece of the given color.

const chess = new Chess()
chess.isAttacked('f3', WHITE)
// -> true (we can attack empty squares)

chess.isAttacked('f6', BLACK)
// -> true (side to move (e.g. the value returned by .turn) is ignored)

chess.load(DEFAULT_POSITION)
chess.isAttacked('e2', WHITE)
// -> true (we can attack our own pieces)

chess.load('4k3/4n3/8/8/8/8/4R3/4K3 w - - 0 1')
chess.isAttacked('c6', BLACK)
// -> true (pieces still attack a square even if they are pinned)

.isCheckmate()

Returns true or false if the side to move has been checkmated.

const chess = new Chess(
  'rnb1kbnr/pppp1ppp/8/4p3/5PPq/8/PPPPP2P/RNBQKBNR w KQkq - 1 3',
)
chess.isCheckmate()
// -> true

.isDraw()

Returns true or false if the game is drawn (50-move rule or insufficient material).

const chess = new Chess('4k3/4P3/4K3/8/8/8/8/8 b - - 0 78')
chess.isDraw()
// -> true

.isDrawByFiftyMoves()

Returns true or false if the game is drawn by 50-move rule.

const chess = new Chess('4k3/4P3/4K3/8/8/8/8/8 b - - 0 78')
chess.isDrawByFiftyMoves()
// -> true

.isInsufficientMaterial()

Returns true if the game is drawn due to insufficient material (K vs. K, K vs. KB, or K vs. KN) otherwise false.

const chess = new Chess('k7/8/n7/8/8/8/8/7K b - - 0 1')
chess.isInsufficientMaterial()
// -> true

.isGameOver()

Returns true if the game has ended via checkmate, stalemate, draw, threefold repetition, or insufficient material. Otherwise, returns false.

const chess = new Chess()
chess.isGameOver()
// -> false

// stalemate
chess.load('4k3/4P3/4K3/8/8/8/8/8 b - - 0 78')
chess.isGameOver()
// -> true

// checkmate
chess.load('rnb1kbnr/pppp1ppp/8/4p3/5PPq/8/PPPPP2P/RNBQKBNR w KQkq - 1 3')
chess.isGameOver()
// -> true

.isStalemate()

Returns true or false if the side to move has been stalemated.

const chess = new Chess('4k3/4P3/4K3/8/8/8/8/8 b - - 0 78')
chess.isStalemate()
// -> true

.isThreefoldRepetition()

Returns true or false if the current board position has occurred three or more times.

const chess = new Chess(
  'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1',
)
// -> true
// rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq occurs 1st time
chess.isThreefoldRepetition()
// -> false

chess.move('Nf3')
chess.move('Nf6')
chess.move('Ng1')
chess.move('Ng8')
// rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq occurs 2nd time
chess.isThreefoldRepetition()
// -> false

chess.move('Nf3')
chess.move('Nf6')
chess.move('Ng1')
chess.move('Ng8')
// rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq occurs 3rd time
chess.isThreefoldRepetition()
// -> true

.load(fen: string, { skipValidation = false, preserveHeaders = false } = {})

Clears the board and loads the provided FEN string. The castling rights, en passant square and move numbers are defaulted to - - 0 1 if omitted. Throws an exception if the FEN i