chessboardjs.com » Documentation https://chessboardjs.

com/docs

chessboardjs.com Home Examples Docs Download

Documentation
▪ Con�g Properties

▪ Methods

▪ Position Object

▪ FEN String

▪ Errors

Con�g Properties
Property / Type Default Description Example

draggable false If true, pieces on the board are draggable to other squares. Draggable
Snapback
Boolean

dropOffBoard 'snapback' If 'snapback', pieces dropped o� the board will return to Draggable
their original square. Snapback
'snapback' or
'trash' If 'trash', pieces dropped o� the board will be removed Draggable Trash
from the board.

This property has no e�ect when draggable is false.

position n/a If provided, sets the initial position of the board. Start Position

'start' or Position FEN

FEN String or
Position Object
Position Object

onChange n/a Fires when the board position changes. onChange

Function The �rst argument to the function is the old position, the
second argument is the new position.

WARNING: do not call any position-changing methods in

your onChange function or you will cause an in�nite loop.

Position-changing methods are: clear(), move(),

position(), and start().

onDragStart n/a Fires when a piece is picked up. onDragStart

Function The �rst argument to the function is the source of the onDragStart
piece, the second argument is the piece, the third argument Prevent Drag
is the current position on the board, and the fourth
argument is the current orientation.

The drag action is prevented if the function returns false.

onDragMove n/a Fires when a dragged piece changes location. onDragMove

Function The �rst argument to the function is the new location of the
piece, the second argument is the old location of the piece,
the third argument is the source of the dragged piece, the
fourth argument is the piece, the �fth argument is the
current position on the board, and the sixth argument is
the current orientation.

1 of 6 24/11/2021, 22:12
chessboardjs.com » Documentation https://chessboardjs.com/docs

Property / Type Default Description Example

onDrop n/a Fires when a piece is dropped. onDrop

Function The �rst argument to the function is the source of the onDrop
dragged piece, the second argument is the target of the Snapback
dragged piece, the third argument is the piece, the fourth
argument is the new position once the piece drops, the �fth onDrop Trash
argument is the old position before the piece was picked
up, and the sixth argument is the current orientation.

If 'snapback' is returned from the function, the piece will

return to it's source square.

If 'trash' is returned from the function, the piece will be

removed.

onMouseoutSquare n/a Fires when the mouse leaves a square. Highlight Legal
Moves
Function The �rst argument to the function is the square that was
left, the second argument is the piece on that square (or
false if there is no piece), the third argument is the current
position of the board, and the fourth argument is the
current orientation.

Note that onMouseoutSquare will not �re during piece drag

and drop. Use onDragMove.

onMouseoverSquare n/a Fires when the mouse enters a square. Highlight Legal
Moves
Function The �rst argument to the function is the square that was
entered, the second argument is the piece on that square
(or false if there is no piece), the third argument is the
current position of the board, and the fourth argument is
the current orientation.

Note that onMouseoverSquare will not �re during piece drag

and drop. Use onDragMove.

onMoveEnd n/a Fires at the end of animations when the board position onMoveEnd
changes.
Function
The �rst argument to the function is the old position, the
second argument is the new position.

onSnapbackEnd n/a Fires when the "snapback" animation is complete when onSnapbackEnd
pieces are dropped o� the board.
Function
The �rst argument to the function is the dragged piece, the
second argument is the square the piece returned to, the
third argument is the current position, and the fourth
argument is the current orientation.

onSnapEnd n/a Fires when the piece "snap" animation is complete. Only Allow Legal
Moves
Function The �rst argument to the function is the source of the
dragged piece, the second argument is the target of the
dragged piece, and the third argument is the piece.

orientation 'white' If provided, sets the initial orientation of the board. Orientation

'white' or
'black'

showNotation true Turn board notation on or o�. Notation

Boolean

2 of 6 24/11/2021, 22:12
chessboardjs.com » Documentation https://chessboardjs.com/docs

Property / Type Default Description Example

sparePieces false If true, the board will have spare pieces that can be Spare Pieces
dropped onto the board.
Boolean
If sparePieces is set to true, draggable gets set to true as
well.

showErrors n/a showErrors is an optional parameter to control how

Chessboard reports errors.
false or
String or Every error in Chessboard has a unique code to help
diagnose problems and search for solutions.
Function
If showErrors is false then errors will be ignored.

If showErrors is 'console' then errors will be sent to

console.log().

If showErrors is 'alert' then errors will be sent to

window.alert().

If showErrors is a function then the �rst argument is the

unique error code, the second argument is an error string,
and an optional third argument is a data structure that is
relevant to the error.

pieceTheme 'img∕chesspieces∕ A template string used to determine the source of piece Piece Theme
wikipedia∕{piece}.png' images. String
String or
Function If pieceTheme is a function the �rst argument is the piece Piece Theme
code. Function

The function should return an <img> source.

appearSpeed 200 Animation speed for when pieces appear on a square.

Number or Note that the "appear" animation only occurs when

'slow' or sparePieces is false.

'fast'

moveSpeed 200 Animation speed for when pieces move between squares Animation Speed
or from spare pieces to the board.
Number or
'slow' or
'fast'

snapbackSpeed 50 Animation speed for when pieces that were dropped Animation Speed
outside the board return to their original square.
Number or
'slow' or
'fast'

snapSpeed 25 Animation speed for when pieces "snap" to a square when Animation Speed
dropped.
Number or
'slow' or
'fast'

trashSpeed 100 Animation speed for when pieces are removed. Animation Speed

Number or
'slow' or
'fast'

3 of 6 24/11/2021, 22:12
chessboardjs.com » Documentation https://chessboardjs.com/docs

Methods
Method Arguments Description Example

clear(useAnimation) false (optional) Removes all the pieces on the board. Clear Board

If useAnimation is false, removes pieces instantly.

Alias of position({}) and position({}, false)

none
destroy() Remove the widget from the DOM. Destroy
Board

none
fen() Returns the current position as a FEN string. Get Position

Alias of position('fen')

none
flip() Flips the board orientation. Orientation

Alias of orientation('flip')

move(move1, move2, etc) 'e2-e4', 'g8-f6', etc Executes one or more moves on the board. Move Pieces

Returns an updated Position Object of the board

including the move(s).

position(fen) 'fen' (optional) Returns the current position as a Position Object. Get Position

If the �rst argument is 'fen', returns the position as a

FEN string.

position(newPosition, Position Object, FEN Animates to a new position. Set Position

useAnimation) string, or 'start'
If useAnimation is false, sets the position instantly.
false (optional)

none
orientation() Returns the current orientation of the board. Orientation

orientation(side) 'white', 'black', or If 'white' or 'black', sets the orientation of the board Orientation
'flip' accordingly.

If 'flip', �ips the orientation.

none
resize() Recalculates board and square sizes based on the Resize
parent element and redraws the board accordingly.

start(useAnimation) false (optional) Sets the board to the start position. Set Position

If useAnimation is false, sets the position instantly.

Alias of position('start') and position('start',

false)

Position Object
You can use a JavaScript object to represent a board position.

The object property names must be algebraic squares (ie: e4, b2, c6, etc) and the values must be a valid piece codes (ie: wP, bK, wQ,

4 of 6 24/11/2021, 22:12
chessboardjs.com » Documentation https://chessboardjs.com/docs

etc).

See an example of using an object to represent a position here.

Chessboard.js exposes the Chessboard.objToFen method to help convert between Position Objects and FEN Strings.

FEN String
You can use Forsyth-Edwards Notation (FEN) to represent a board position.

Note that FEN notation captures more information than chessboard.js requires, like who's move it is and whether or not castling is
allowed. This information will be ignored; only the position information is used.

See an example of using a FEN String to represent a position here and here.

Chessboard.js exposes the Chessboard.fenToObj method to help convert a FEN String to a Position Object.
The object property names must be algebraic squares (ie: e4, b2, c6, etc) and the values must be a valid piece codes (ie: wP, bK, wQ,

Errors
Chessboard.js has an error system designed to inform you when you use the API incorrectly.

Every alert has a unique code associated with it and you can control how the errors are presented with the showErrors con�g
option.

Error ID Error Text More Information

1001 The �rst argument to Chessboard() cannot be an empty The �rst argument to the Chessboard() constructor should
string. be the id of a DOM element or a reference to a single DOM
element.

1003 The �rst argument to Chessboard() must be an ID or a The �rst argument to the Chessboard() constructor should
single DOM node. be the id of a DOM element or a reference to a single DOM
element.

1005 Unable to �nd a valid version of jQuery. Please include Chessboard requires jQuery version 1.8.3 or higher.
jQuery 1.8.3 or higher on the page.

2826 Invalid move passed to the move method. Moves must be a string in the form of 'e2-e4', 'b8-c6', etc.

5482 Invalid value passed to the orientation method. The �rst argument to the orientation method must be
'white', 'black', or 'flip'.

6482 Invalid value passed to the position method. Position must be either 'start', a valid FEN String, or a
valid Position Object.

7263 Invalid value passed to con�g.position Position must either be 'start', a valid FEN String, or a
Position Object.

8272 Unable to build image source for cfg.pieceTheme. This is an internal Chessboard error that you should never
see.

If you see this error please open a GitHub issue.

chessboard.js is released under the MIT License by Chris Oakman

5 of 6 24/11/2021, 22:12