oakmac / chessboardjs

JavaScript chessboard

chessboard.js

NOTE: chessboard.js can be found on npm as @chrisoakman/chessboardjs

chessboard.js is a JavaScript chessboard component. It depends on jQuery v3.4.1 (or higher).

Please see chessboardjs.com for documentation and examples.

Project Status (Dec 2022)

I am currently focusing my efforts on chessboard2.

What is chessboard.js?

chessboard.js is a standalone JavaScript Chess Board. It is designed to be "just a board" and expose a powerful API so that it can be used in different ways. Here's a non-exhaustive list of things you can do with chessboard.js:

• Use chessboard.js to show game positions alongside your expert commentary.
• Use chessboard.js to have a tactics website where users have to guess the best move.
• Integrate chessboard.js and chess.js with a PGN database and allow people to search and playback games (see Example 5000)
• Build a chess server and have users play their games out using the chessboard.js board.

chessboard.js is flexible enough to handle any of these situations with relative ease.

What can chessboard.js not do?

The scope of chessboard.js is limited to "just a board." This is intentional and makes chessboard.js flexible for building a variety of chess-related applications.

To be specific, chessboard.js does not understand anything about how the game of chess is played: how a knight moves, whose turn is it, is White in check?, etc.

Fortunately, the chess.js library deals with exactly this sort of problem and plays nicely with chessboard.js's flexible API. Some examples of chessboard.js combined with chess.js: Example 5000, Example 5001, Example 5002

Docs and Examples

• Docs - https://chessboardjs.com/docs
• Examples - https://chessboardjs.com/examples

Developer Tools

# create a build in the build/ directory
npm run build

# re-build the website
npm run website

License

MIT License

chessboardjs's Issues

add example: PGN viewer

feature request: movelist and replayer ability

Another feature idea:

Basically, what you see here (click on a move, then hold down the right or left arrow keys)

http://andrewphoy.github.io/chess-replayer/

Again, apologies, you've probably already thought of this. Just wanted to see it documented here.

I'd be willing to help out if you wish. I'm a bit new to the whole github scene.

feature request: add ability to move pieces via clicking on start, then destination square

Really enjoy your work thus far.

I noticed the only way to move pieces currently is to click-drag them from their starting square to their destination square.

Adding an additional modality, in which you can click on a piece (thereby selecting it), then click on its destination square, would accommodate those users who for whatever reason naturally expect such behavior.

Just a small suggestion, which you've probably already thought of.

Need method to handle a board resize

Or add an event handler on the container element to check for this?

this might be useful:
board.resize();

Board Redrawing OnDrop? (Probably not really an issue)

I'm having a heck of a time figuring out why my implementation re-draws the board onDrop.

Example: http://inb.tw:8080/chess#/george/12/cm5icWtibnIvcHBwcHBwcHAvOC84LzRQMy84L1BQUFAxUFBQL1JOQlFLQk5SIGIgS1FrcSBlMyAwIDE=

This is the JS: http://inb.tw:8080/js/ss.chess.js

OnDrop I see all of the pieces being re-requested (in the network tab of the dev tools).

Any thoughts on what might be causing this?

Please document requirements

Hi,

It seems chessboard.js requires jQuery to be loaded, but I cannot find this anywhere in the documentation (and jQuery is not included in the archive). Could you please document this somewhere, preferrably in “Getting started”? (Also, which versions/features you'd need would also be nice.)

Thanks!

update move() method to have no animations

1. if "false" is passed in to any of the arguments, no animations
2. allow an array of moves

need to be able to disable animations

ie: If you set snapSpeed to false, then there should be no snap animation at all.

Ditto for all the other animation configs.

Add example for onSnapEnd

Square highlights get lost on board re-size or orientation change.

This is happening because the board gets redrawn into the DOM on both of these events and square highlights don't get saved in state.

Might need to reconsider adding the .highlight() method for squares in order to fix this.

moves() method should be able to accept algebraic notation

Which would make the board work easily with PGN

Drop pieces onto board to build position

Users need to be able to drop a piece onto the board from outside the board.

Consider: stationary pieces ala chesspaste.com?

What other API methods are needed to make this happen?

Optimization: save elements in memory; don't select them everytime

Create example: dropOffBoard: 'trash'

add touch events

add "pieceTaken" to the onDrop method

Should tell you whether or not a piece is captured on an onDrop event.

need to add an "appearSpeed" config option

For when pieces appear on the board.

Note: this only happens when sparePieces = false

add an onMouseOver event

Do we need an onMouseOver event for mousing over squares? Think it could be useful.

create the homepage

Put util functions on ChessBoard.prototype

Optimization: put pieces in CSS sprites and/or convert to SVG

Assumed pawn promotion to queen.

Using http://chessboardjs.com/examples/5000 it seems that pawn promotion is always assumed to be to queen. Promotion to any piece (NBR or Q) is possible and the player needs a mechanism to decide.

Guide to contribute

Well, it was a bit hard to set up the project to work in my machine. I spent some minutes configuring the project (changing config.php, .htacess and etc).
What do you think about writing some little info about how to contribute?

Animation speeds need to be configurable

'move', 'snap', 'snapback' are the three I can think of

what else?

Add example: drag and drop with no animations

Sync docs with versions

For example, onSnapEnd is documented on chessboardjs.com where the most recent version is v0.1.0. But onSnapEnd handling was not added until 9 days after 0.1.0 was released (acb1074). I spun my wheels for some time debugging why the onSnapEnd event did not fire.

Consider noting in the docs when a feature is added.

No way to castle on move()

Hi,

As the title says. You can board.move("e1-g1"), but only the king moves. I guess the closest you'd get would be board.move("e1-g1", "h1-f1"), but that's two moves as I understand it, and requires the client to keep track of the king's state itself.

Unicode chess symbols

Please consider using the unicode symbols points for your .png files. Alternately, wikipedia has .svg versions of your icons.

♖ ♘ ♗ ♕ ♔ ♗ ♘ ♖
♙ ♙ ♙ ♙ ♙ ♙ ♙ ♙



♟ ♟ ♟ ♟ ♟ ♟ ♟ ♟
♜ ♞ ♝ ♛ ♚ ♝ ♞ ♜

add error handling system

Alice Chess

How can I create Alice Chess board?

Basically I have two boards, and whenever piece moves, at the end of move it moves to same place in another board.

Also, I would like to have small black/white dot in another board where pieces are on the another (can be any picture, it can be changed later). For example, if I have piece in board 2 in place A3, in board 1 place A3 is small dot indicating that there is piece in that place, in another board.

For now I have following:

var init = function() {

var onDrop = function(source, target, piece, newPos) {
board2.move(source + '-' + target);
};

var onDrop2 = function(source, target) {
board1.move(source + '-' + target);
};

var cfg = {
draggable: true,
dropOffBoard: 'snapback',
position: 'start',
onDrop: onDrop,
sparePieces: true
};
var cfg2 = {
draggable: true,
dropOffBoard: 'snapback',
position: 'start',
onDrop: onDrop2,
sparePieces: true
};
var board1 = new ChessBoard('board1', cfg);
var board2 = new ChessBoard('board2', cfg2);

}; // end init()
$(document).ready(init);

---

When I move something on one board, it follows on another. This would be all I need if 1) after move it would change image of moved piece on both boards and 2) Start in one board with one picture set (pieces) and another on board 2 (dots)

add vanilla example for onMouseoverSquare and onMouseoutSquare

Function to Check validity of a move

As much as I love this library, and love you for making it, doesn't it severely lack a function that checks if a given move is valid of not? I can move just about anything to anything =/ I understand that there might be a need for a movement function that bypasses these rules so you could set up the board etc, but an isValidMove() function would make such a nice addition.

PS: I'd be happy to write the code for you if you think this might be too much work

New example showing FEN string as the board is updated

Piece themeing

Need to figure out how to do this.

how to get moves for a piece regardless of who's turn it is

Hi Chris, how would I get the moves of a piece regardless of who's turn it is?

finish documentation

New example showing integration with Chess.js

And PGN parsing

Need a method to highlight squares

How will this work with the highlighting when dragging pieces?

// return an array of currently highlighted squares
board.highlight();

// highlight some squares
board.highlight('e2', 'e3', 'e4');

// clear highlight
board.highlight('clear');

Minor: Pawns should animate on their column if possible

This is a really minor enhancement; low priority.

When calculating animations, pawns should search their column first when moving square-to-square, then search outside their column.

This would prevent the "cross-pawns" animation back to their starting point, which is slightly jarring.

Cache images

Images are re-requested every animation update.
This may also be the cause of #52
My solution was to cache the images in base64 url strings,
which is implemented here: http://queens.zolmeister.com/

It looks like this:

var imgCache = {}
function cacheImages() {
  var pieces = ['wK', 'wQ', 'wR', 'wB', 'wN', 'wP', 'bK', 'bQ', 'bR', 'bB', 'bN', 'bP'];
  pieces.forEach(function(piece) {
    var img = new Image()
    img.onload = function() {
      imgCache[piece] = getBase64Image(img)
    }
    img.src = buildPieceImgSrc(piece)
  })

  function getBase64Image(img) {
    var canvas = document.createElement("canvas");
    canvas.width = img.width;
    canvas.height = img.height;
    var ctx = canvas.getContext("2d");
    ctx.drawImage(img, 0, 0);
    var dataURL = canvas.toDataURL("image/png");
    return dataURL;     
  }
}

function buildPieceImgSrc(piece) {
  if(imgCache[piece]) return imgCache[piece]
...

onMoveEnd only fires in onFinish of doAnimations

A simple configuration never invokes the method.

EDIT: A user of the code will almost certainly need to differentiate between a post-valid-move onchange event and all other onchange events. The naming of the onMoveEnd method confused me at first, but now I understand its purpose isn't serving as a post onDrop event.

long term: separate the site code from the board code

The code that powers the website really should be it's own repo and this repo should just have the code and content for this component.

ie: this repo shouldn't contain any PHP

how to iterate through all of the remaining pieces of one side

Hi Chris, how would I iterate through all the remaining pieces of one side returning piece and square ? (possibly paired in an object)

create "lock" variable to prevent position-changing methods when executing the onChange function

Does this make sense to do?

This would prevent a user from creating an infinite loop, but it would also make their position-changing functions magically stop working if executed in their onChange function.

Better support for the Google Closure compiler

Hi,

I'm compiling chessboard.js together with other code using the Google Closure compiler. Would you be interested in making a few small changes to make it compatible with the advanced optimization level?

Basically the only thing you're doing that's a problem is accessing properties sometimes with [] and sometimes with a dot, because the compiler renames any properties that are ever accessed with a dot. This manifests itself in two places:

1. You use window['ChessBoard'] one place, and window.ChessBoard somewhere else. Using window.ChessBoard everywhere would make the renaming consistent (or you cold use window['ChessBoard'] everywhere if you want it to be available to external JavaScript that's not compiled together with chessboard.js, but I think this might inhibit some optimizations).
2. The ”CSS” array is accessed almost always with the dot, but you also use “white” and “black” with []. The simplest thing here is simply moving the constants away from the same array as the one you index variably:

+var CSSColor = {};
+CSSColor['white'] = 'white-1e1d7';
+CSSColor['black'] = 'black-3c85d';

Create a .config() method

// return the current config object
board.config();

// change a single config value
board.config('onChange', fn);

// update the config with an object
board.config({
'draggable': false,
'orientation': 'black
};

new example: hover over square showing legal moves

Pieces flickers on update

Hi,

When I do board.position(fen), it would seem the pieces are somehow redrawn; at least they flicker ever so shortly during the move somehow. Especially for the pieces that stand still, maybe this could avoided?

I don't think this has anything to do with my code; it happens on e.g. http://chessboardjs.com/examples#3001 when I switch positions.

I'm using Chrome 31.0.1650.57 on Linux.

create a favicon

How to choose pawn promotion?

It there are option to be able to choose to what promote the pawn?