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.
Run the following command to install the most recent version of chess.js from NPM:
npm install chess.js@1.0.0-alpha.0or install the latest development version straight from GitHub:
npm install git+https://github.com/jhlywa/chess.js.gitThe 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())By design, chess.js is headless and does not include a user interface. Many developers have had success integrating chess.js with the chessboard.js library. See chessboard.js - Random vs Random for an example.
The Chess() constructor takes an optional parameter which specifies the board configuration in Forsyth-Edwards Notation (FEN). Throw an exception if an invalid FEN string is provided.
// board defaults to the starting position when called with no parameters
const chess = new Chess()
// pass in a FEN string to load a particular position
const chess = new Chess(
'r1k4r/p2nb1p1/2b4p/1p1n1p2/2PP4/3Q1NB1/1P3PPP/R5K1 b - - 0 19'
)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'Returns an 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'}]]Clears the board.
chess.clear()
chess.fen()
// -> '8/8/8/8/8/8/8/8 w - - 0 1' <- empty boardDelete and return 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"
chess.deleteComment()
// -> "giuoco piano"
chess.getComment()
// -> undefinedDelete and return 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.deleteComments()
// -> [
// {
// 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"
// }
// ]
chess.getComments()
// -> []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.
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'Returns the piece on the square:
chess.clear()
chess.put({ type: chess.PAWN, color: chess.BLACK }, 'a5') // put a black pawn on a5
chess.get('a5')
// -> { type: 'p', color: 'b' },
chess.get('a6')
// -> nullRetrieve 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"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"
// }
// ]Allows header information to be added to PGN output. Any number of key/value pairs can be passed to .header().
chess.header('White', 'Robert James Fischer')
chess.header('Black', 'Mikhail Tal')
// or
chess.header('White', 'Morphy', 'Black', 'Anderssen', 'Date', '1858-??-??')Calling .header() without any arguments returns the header information as an object.
chess.header()
// -> { White: 'Morphy', Black: 'Anderssen', Date: '1858-??-??' }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 })
// -->
// [
// {
// fen: 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1',
// color: 'w',
// piece: 'p',
// from: 'e2',
// to: 'e4',
// san: 'e4',
// lan: 'e2e4',
// flags: 'b'
// },
// {
// fen: 'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1',
// color: 'b',
// piece: 'p',
// from: 'e7',
// to: 'e5',
// san: 'e5',
// lan: 'e7e5',
// flags: 'b'
// },
// {
// fen: 'rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 0 2',
// color: 'w',
// piece: 'p',
// from: 'f2',
// to: 'f4',
// san: 'f4',
// lan: 'f2f4',
// flags: 'b'
// },
// {
// fen: 'rnbqkbnr/pppp1ppp/8/4p3/4PP2/8/PPPP2PP/RNBQKBNR b KQkq - 0 2',
// color: 'b',
// piece: 'p',
// from: 'e5',
// to: 'f4',
// san: 'exf4',
// lan: 'e5f4',
// flags: 'c',
// captured: 'p'
// }
// ]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()
// -> trueReturns true if the square is attacked by any piece of the given color.
const chess = new Chess()
chess.isAttacked('f3', Chess.WHITE)
// -> true (we can attack empty squares)
chess.isAttacked('f6', Chess.BLACK)
// -> true (side to move (e.g. the value returned by .turn) is ignored)
chess.load(Chess.DEFAULT_POSITION)
chess.isAttacked('e2', Chess.WHITE)
// -> true (we can attack our own pieces)
chess.load('4k3/4n3/8/8/8/8/4R3/4K3 w - - 0 1')
chess.isAttacked('c6', Chess.BLACK)
// -> true (pieces still attack a square if even they are pinned)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()
// -> trueReturns 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()
// -> trueReturns 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()
// -> trueReturns 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()
// -> trueReturns 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()
// -> trueReturns 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()
// -> trueClears the board and loads the provided FEN string. The castling rights, en
passant square and move numbers are defaulted to - - 0 1 if ommitted. Throws
an exception if the FEN is invalid.
const chess = new Chess()
chess.load('4r3/8/2p2PPk/1p6/pP2p1R1/P1B5/2P2K2/3r4 w - - 1 45')
try {
chess.load('4r3/8/X12XPk/1p6/pP2p1R1/P1B5/2P2K2/3r4 w - - 1 45')
} catch (e) {
console.log(e)
}
// -> Error: Invalid FEN: piece data is invalid (invalid piece)Load the moves of a game stored in
Portable Game Notation.
pgn should be a string. Options is an optional object which may contain a
string newlineChar and a boolean sloppy.
The newlineChar is a string representation of a valid RegExp fragment and is
used to process the PGN. It defaults to \r?\n. Special characters should not
be pre-escaped, but any literal special characters should be escaped as is
normal for a RegExp. Keep in mind that backslashes in JavaScript strings must
themselves be escaped (see sloppyPgn example below). Avoid using a
newlineChar that may occur elsewhere in a PGN, such as . or x, as this
will result in unexpected behavior.
The sloppy flag is a boolean that permits chess.js to parse moves in
non-standard notations. See .move documentation for more information about
non-SAN notations.
The method will throw and exception if the PGN failed to parse.
const chess = new Chess()
const pgn = [
'[Event "Casual Game"]',
'[Site "Berlin GER"]',
'[Date "1852.??.??"]',
'[EventDate "?"]',
'[Round "?"]',
'[Result "1-0"]',
'[White "Adolf Anderssen"]',
'[Black "Jean Dufresne"]',
'[ECO "C52"]',
'[WhiteElo "?"]',
'[BlackElo "?"]',
'[PlyCount "47"]',
'',
'1.e4 e5 2.Nf3 Nc6 3.Bc4 Bc5 4.b4 Bxb4 5.c3 Ba5 6.d4 exd4 7.O-O',
'd3 8.Qb3 Qf6 9.e5 Qg6 10.Re1 Nge7 11.Ba3 b5 12.Qxb5 Rb8 13.Qa4',
'Bb6 14.Nbd2 Bb7 15.Ne4 Qf5 16.Bxd3 Qh5 17.Nf6+ gxf6 18.exf6',
'Rg8 19.Rad1 Qxf3 20.Rxe7+ Nxe7 21.Qxd7+ Kxd7 22.Bf5+ Ke8',
'23.Bd7+ Kf8 24.Bxe7# 1-0',
]
chess.loadPgn(pgn.join('\n'))
chess.fen()
// -> 1r3kr1/pbpBBp1p/1b3P2/8/8/2P2q2/P4PPP/3R2K1 b - - 0 24
chess.ascii()
// -> ' +------------------------+
// 8 | . r . . . k r . |
// 7 | p b p B B p . p |
// 6 | . b . . . P . . |
// 5 | . . . . . . . . |
// 4 | . . . . . . . . |
// 3 | . . P . . q . . |
// 2 | P . . . . P P P |
// 1 | . . . R . . K . |
// +------------------------+
// a b c d e f g h'
// Parse non-standard move formats and unusual line separators
const sloppyPgn = [
'[Event "Wijk aan Zee (Netherlands)"]',
'[Date "1971.01.26"]',
'[Result "1-0"]',
'[White "Tigran Vartanovich Petrosian"]',
'[Black "Hans Ree"]',
'[ECO "A29"]',
'',
'1. Pc2c4 Pe7e5', // non-standard
'2. Nc3 Nf6',
'3. Nf3 Nc6',
'4. g2g3 Bb4', // non-standard
'5. Nd5 Nxd5',
'6. c4xd5 e5-e4', // non-standard
'7. dxc6 exf3',
'8. Qb3 1-0',
].join(':')
chess.loadPgn(sloppyPgn, { newlineChar: ':' })
// Error: Invalid move in PGN: Pc2c4
chess.loadPgn(sloppyPgn, { newlineChar: ':', sloppy: true })
chess.fen()
// -> 'r1bqk2r/pppp1ppp/2P5/8/1b6/1Q3pP1/PP1PPP1P/R1B1KB1R b KQkq - 1 8'Makes a move on the board and returns a move object if the move was legal. The move argument can be either a string in Standard Algebraic Notation (SAN) or a move object. Throws an 'Illegal move' exception if the move was illegal.
const chess = new Chess()
chess.move('e4')
// -> { color: 'w', from: 'e2', to: 'e4', flags: 'b', piece: 'p', san: 'e4' }
chess.move('nf6') // SAN is case sensitive!!
// Error: Invalid move: nf6
chess.move('Nf6')
// -> { color: 'b', from: 'g8', to: 'f6', flags: 'n', piece: 'n', san: 'Nf6' }A move object contains to, from and, promotion (only when necessary)
fields.
const chess = new Chess()
chess.move({ from: 'g2', to: 'g3' })
// -> { color: 'w', from: 'g2', to: 'g3', flags: 'n', piece: 'p', san: 'g3' }An optional { sloppy: true } flag can be used to parse a variety of
non-standard move notations:
const chess = new Chess()
// various forms of Long Algebraic Notation
chess.move('e2e4', { sloppy: true })
// -> { color: 'w', from: 'e2', to: 'e4', flags: 'b', piece: 'p', san: 'e4' }
chess.move('e7-e5', { sloppy: true })
// -> { color: 'b', from: 'e7', to: 'e5', flags: 'b', piece: 'p', san: 'e5' }
chess.move('Pf2f4', { sloppy: true })
// -> { color: 'w', from: 'f2', to: 'f4', flags: 'b', piece: 'p', san: 'f4' }
chess.move('Pe5xf4', { sloppy: true })
// -> { color: 'b', from: 'e5', to: 'f4', flags: 'c', piece: 'p', captured: 'p', san: 'exf4' }
// correctly parses incorrectly disambiguated moves
chess = new Chess(
'r2qkbnr/ppp2ppp/2n5/1B2pQ2/4P3/8/PPP2PPP/RNB1K2R b KQkq - 3 7'
)
chess.move('Nge7') // Ne7 is unambiguous because the knight on c6 is pinned
// Error: Invalid move: Nge7
chess.move('Nge7', { sloppy: true })
// -> { color: 'b', from: 'g8', to: 'e7', flags: 'n', piece: 'n', san: 'Ne7' }Returns a list of legal moves from the current position. This function takes an optional parameter which can be used to generate detailed move objects or to restrict the move generator to specific squares or pieces.
const chess = new Chess()
chess.moves()
// -> ['a3', 'a4', 'b3', 'b4', 'c3', 'c4', 'd3', 'd4', 'e3', 'e4',
// 'f3', 'f4', 'g3', 'g4', 'h3', 'h4', 'Na3', 'Nc3', 'Nf3', 'Nh3']
chess.moves({ square: 'e2' }) // single square move generation
// -> ['e3', 'e4']
chess.moves({ piece: 'n' }) // generate moves for piece type
// ['Na3', 'Nc3', 'Nf3', 'Nh3']
chess.moves({ verbose: true }) // return verbose moves
// -> [{ color: 'w', from: 'a2', to: 'a3',
// flags: 'n', piece: 'p', san 'a3'
// # a `captured` field is included when the move is a capture
// # a `promotion` field is included when the move is a promotion
// },
// ...
// ]The color field indicates the color of the moving piece (w or b).
The from and to fields are from and to squares in algebraic notation.
The piece, captured, and promotion fields contain the lowercase
representation of the applicable piece (pnbrqk). The captured and
promotion fields are only present when the move is a valid capture or
promotion.
The san field is the move in Standard Algebraic Notation (SAN).
The flags field contains one or more of the string values:
n- a non-captureb- a pawn push of two squarese- an en passant capturec- a standard capturep- a promotionk- kingside castlingq- queenside castling
A flags value of pc would mean that a pawn captured a piece on the 8th rank
and promoted.
Returns the game in PGN format. Options is an optional parameter which may include max width and/or a newline character settings.
const chess = new Chess()
chess.header('White', 'Plunky', 'Black', 'Plinkie')
chess.move('e4')
chess.move('e5')
chess.move('Nc3')
chess.move('Nc6')
chess.pgn({ maxWidth: 5, newline: '<br />' })
// -> '[White "Plunky"]<br />[Black "Plinkie"]<br /><br />1. e4 e5<br />2. Nc3 Nc6'Place a piece on the square where piece is an object with the form { type: ...,
color: ... }. Returns true if the piece was successfully placed, otherwise, the
board remains unchanged and false is returned. put() will fail when passed an
invalid piece or square, or when two or more kings of the same color are placed.
chess.clear()
chess.put({ type: chess.PAWN, color: chess.BLACK }, 'a5') // put a black pawn on a5
// -> true
chess.put({ type: 'k', color: 'w' }, 'h1') // shorthand
// -> true
chess.fen()
// -> '8/8/8/p7/8/8/8/7K w - - 0 0'
chess.put({ type: 'z', color: 'w' }, 'a1') // invalid piece
// -> false
chess.clear()
chess.put({ type: 'k', color: 'w' }, 'a1')
// -> true
chess.put({ type: 'k', color: 'w' }, 'h1') // fail - two kings
// -> falseRemove and return the piece on square.
chess.clear()
chess.put({ type: chess.PAWN, color: chess.BLACK }, 'a5') // put a black pawn on a5
chess.put({ type: chess.KING, color: chess.WHITE }, 'h1') // put a white king on h1
chess.remove('a5')
// -> { type: 'p', color: 'b' },
chess.remove('h1')
// -> { type: 'k', color: 'w' },
chess.remove('e1')
// -> nullReset the board to the initial starting position.
Comment on the current position.
const chess = new Chess()
chess.move('e4')
chess.setComment("king's pawn opening")
chess.pgn()
// -> "1. e4 {king's pawn opening}"Returns the color of the square ('light' or 'dark').
const chess = Chess()
chess.squareColor('h1')
// -> 'light'
chess.squareColor('a7')
// -> 'dark'
chess.squareColor('bogus square')
// -> nullReturns the current side to move.
chess.load('rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1')
chess.turn()
// -> 'b'Takeback the last half-move, returning a move object if successful, otherwise null.
const chess = new Chess()
chess.fen()
// -> 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'
chess.move('e4')
chess.fen()
// -> 'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1'
chess.undo()
// -> { color: 'w', from: 'e2', to: 'e4', flags: 'b', piece: 'p', san: 'e4' }
chess.fen()
// -> 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'
chess.undo()
// -> nullReturns a validation object specifying validity or the errors found within the FEN string.
chess.validateFen('2n1r3/p1k2pp1/B1p3b1/P7/5bP1/2N1B3/1P2KP2/2R5 b - - 4 25')
// -> { ok: true }
chess.validateFen('4r3/8/X12XPk/1p6/pP2p1R1/P1B5/2P2K2/3r4 w - - 1 45')
// -> { ok: false,
// error: '1st field (piece positions) is invalid [invalid piece].' }- The en passant square and castling flags aren't adjusted when using the put/remove functions (workaround: use .load() instead)