js-chessboard is a simple JavaScript library that allows you to create chessboards on websites.

This library uses alpha pieces and it is "free for personal non commercial use".

You can report bugs or make suggestions in this site.

• Move pieces by dragging and dropping with both the mouse and touch

• Set position with FEN

• Right-click to highlight squares

• Right-click and drag to add arrows

• Move pieces with click

• Resize board with mouse

• Transition between moves

• Play with legal moves

• Change themes

• Read PGN

More features will be added from time to time.

npm install js-chessboard

import { initChessboard } from "https://cdn.jsdelivr.net/npm/js-chessboard@2.0.0/src/chessboard.min.js"

import { initChessboard } from "./path/to/chessboard.js"

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/js-chessboard@2.0.0/css/chessboard.min.css">

<link rel="stylesheet" href="./path/to/style.css">

import { addCss } from "./path/to/chessboard.js"
addCss();

The initChessboard function creates a div and creates the chessboard with the given configuration inside that div and then puts this div into the given element and returns chessboard as an object.

let elem = document.querySelector("#div");
let board = initChessboard(elem, config);

Sets the size of the chessboard. Must be a number. The default value is 400.

Sets the orientation of the chessboard. Must be a string. Can be either white or black. The default is white.

Sets the position of the chessboard. Can be a FEN string, a position object or a predefined position string. Predefined positions are "start" and "empty". The default position is the start position.

Sets if the user can take same color pieces or not. Must be a boolean. Default value is false.

Sets if the ghost piece will be visible or not while dragging a piece. Default value is true,

Sets if the user can highlight squares with right clicking. Default value is true.

Sets if the user can add arrows with right click drag. Default value is true.

Adds resize arrow to the bottom right corner if true. Default value is false.

Sets the minimum possible value for the board size. Default is null.

Sets the maximum possible value for the board size. Default is null.

Auto promotes to that piece instead of showing promotion window if set. Can be "q" (queen), "r" (rook), "n" (knight), "b" (bishop) or false for disable auto promotion. Default is false.

config = {
    size: 400,
    orientation: "white",
    position: "start",
    takeSameColor: false,
    showGhostPiece: true,
    enableHighlights: true,
    enableArrows: true,
    resizable: false,
    minSize: null,
    maxSize: null,
    autoPromoteTo: false
}

Returns element

board.element(); // element

Returns size

board.size(); // 400

Returns current orientation

board.orientation(); // "white"

Returns the current position as an object

Returns the current position as a fen string

board.fen(); // "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"

Returns the last played move as a string. This property's format is "x1 x2 x3 x4". x1 and x2 are from and to squares. x3 is taken piece if a piece is taken. Otherwise it is "-". x4 is the promoted piece if there was a promotion. Otherwise it is "-".

board.lastMove(); // "e2 e4 - -" -> e2 to e5 no piece is taken and no promotion
board.lastMove(); // "d4 e5 bp -" d4 to e5 and black pawn is taken no promotion
board.lastMove(); // "f7 g8 - wr" f7 to g8 no piece is taken and promoted to white rook

Returns the last moved piece as HTMLElement

Returns arrows as an array of HTMLElements

Returns the current showGhostPiece value if no parameter is passed or the passed parameter is not boolean. Otherwise it sets the showGhostPiece value and returns the new value.

Returns the current enableHighlight value if no parameter is passed or the passed parameter is not boolean. Otherwise it sets the enableHighlight value and returns the new value.

Returns the current enableArrows value if no parameter is passed or the passed parameter is not boolean. Otherwise it sets the enableArrows value and returns the new value.

Returns the current minSize value if no parameter is passed or the passed parameter is not boolean. Otherwise it sets the minSize value and returns the new value.

Returns the current maxSize value if no parameter is passed or the passed parameter is not boolean. Otherwise it sets the maxSize value and returns the new value.

Returns the current autoPromoteTo value if no parameter is passed or the passed parameter is not a valid value. Otherwise it sets the autoPromoteTo value and returns the new value.

Returns move history as a string array. Moves format is same as lastMove. Move history and move counts changes if user goes back to another move and then makes a different move. .setPosition() clears move history and move counts.

Returns total number of moves.

Returns current move count.

Flips board and returns new orientation.

Sets the orientation of the chessboard to the given orientation and returns the new orientation if the given orientation is valid, otherwise undefined.

board.setOrientation("black"); // "black"
board.setOrientation("example"); // undefined

Sets the position of the board with the given position. The position parameter can be a position object or a fen string. Returns the fen of the new position if the position is valid, otherwise undefined. Clears move history and move counts.

board.setOrientation("empty"); // "8/8/8/8/8/8/8/8"

Places the piece with the given name in the given square. Returns undefined if pieceName or square is invalid or there is already a piece in the given square, otherwise returns piece as a HTMLElement.

// Places white rook to f4 square
board.setPiece("wr", "f4"); // img.piece

Returns the piece if there is a piece on the given square, null if there is not, undefined if the given square is invalid.

board.getPiece("g5"); // img.piece
board.getPiece("h9"); // undefined

Returns the square as an HTMLElement if there is a square on the given square, null if there is not, undefined if the given square is invalid. Square parameter must be string.

board.getSquare("g5"); // div.square
board.getSquare("h9"); // undefined

Moves a piece from fromSquare to toSquare. Returns undefined if the one of the squares invalid or there is no piece, otherwise returns the moved piece. If animation is true then the last animation will be cut and the piece will move with animation. If takeSameColor is true then the piece will take same colored piece in the toSquare, if false then the piece won't move if there is a piece with the same color in the toSquare. If promoteTo is set to a piece ("q","r","n","b") then it automatically promotes to that piece instead of showing promotion window if there is a promotion.

board.movePiece("e2", "e4"); // img.piece

Adds arrow from fromSquare to toSquare or removes arrow if there is already an arrow with the same squares. Returns the created arrow as a HTMLElement, or undefined if one of the squares is invalid.

board.addArrow("b5", "c3"); // line

Resizes the board. Returns new size or undefined if size is not a number.

board.resize(600); // 600

Returns the current resizable value if no parameter is passed or the passed parameter is not boolean. Otherwise it sets the resizable value and returns the new value.

Goes back one move and decreases the currentMoveCount by 1. If animation is true it animates the move. Returns currentMoveCount if it can goes back. Otherwise returns undefined.

Goes forward one move and increases the currentMoveCount by 1. If animation is true it animates the move. Returns currentMoveCount if it can goes forward. Otherwise returns undefined.

Goes back to first move.

Goes forward to last move.

Removes all pieces from board.

board.clearPieces();

Clears all highlights from higlighted squares.

board.clearHighlights();

Clears all arrows from board.

board.clearArrows();

Destroys board and removes the element from html.

board.destroy();

Adds css file to the html document

import { addCss } from "./path/to/chessboard.js"
addCss();

You can use a JavaScript object to define a position. Property names must be squares and values must be piece name.

let position = {
    e8 = "bk",
    h7 = "wr",
    d5 = "wk",
    e5 = "wp",
    f5 = "br"
}

 =>     +------------------------+
      8 | .  .  .  .  k  .  .  . |
      7 | .  .  .  .  .  .  .  R |
      6 | .  .  .  .  .  .  .  . |
      5 | .  .  .  K  P  r  .  . |
      4 | .  .  .  .  .  .  .  . |
      3 | .  .  .  .  .  .  .  . |
      2 | .  .  .  .  .  .  .  . |
      1 | .  .  .  .  .  .  .  . |
        +------------------------+
          a  b  c  d  e  f  g  h'

Dispatched when the user clicks on a piece. The event has the piece property, which is the clicked piece as an HTMLElement.

board.addEventListener("pieceClick", (e) => {
  console.log(e.piece);
});

Dispatched when the user starts dragging a piece. The event has piece property, which is the piece being dragged as an HTMLElement.

board.addEventListener("pieceDragStart", (e) => {
  console.log(e.piece);
});

Dispatched when the user drags a piece. The event has piece property, which is the piece being dragged as an HTMLElement.

board.addEventListener("pieceDrag", (e) => {
  console.log(e.piece);
});

Dispatched when the user finishes dragging a piece. The event has piece property, which is the piece being dragged as an HTMLElement.

board.addEventListener("pieceDragEnd", (e) => {
  console.log(e.piece);
});

Dispatched when a piece is moved. The event has piece property, which is the moved piece as an HTMLElement, from property, which is the old square of the piece as a string, to property, which is the new square of the piece as a string.

board.addEventListener("pieceMove", (e) => {
  console.log(e.piece);
  console.log(e.from);
  console.log(e.to);
});

Dispatched when the position is changes. The event has oldPos property which is the old position as a FEN string and newPos property which is the new position as a FEN string.

board.addEventListener("positionChange", (e) => {
  console.log(e.oldPos);
  console.log(e.newPos);
});

Dispatched when the user drags a piece over a square. The event has piece property, which is the piece being dragged as an HTMLElement and square property as a string.

board.addEventListener("overSquare", (e) => {
  console.log(e.piece);
  console.log(e.square);
});

Dispatched when the user drops a piece over a square. The event has piece property, which is the dropped piece as an HTMLElement and square property as a string.

board.addEventListener("dropOverSquare", (e) => {
  console.log(e.piece);
  console.log(e.square);
});

Dispatched when the user opens the promotion window. The event has piece property, which is the piece that is being promoted as an HTMLElement.

board.addEventListener("promotionAttempt", (e) => {
  console.log(e.piece);
});

Dispatched when the user promotes a piece. The event has piece property, which is the promoted piece as an HTMLElement, from property, which is the old square of the piece as a string, to property, which is the new square of the piece as a string, and promoteTo property, which is the new piece as a string.

board.addEventListener("promotion", (e) => {
  console.log(e.piece);
  console.log(e.from);
  console.log(e.to);
  console.log(e.promoteTo);
});

Dispatched when the user cancels a promotion. The event has piece property, which is the piece that the user attempted to promote as an HTMLElement.

board.addEventListener("promotionCancel", (e) => {
  console.log(e.piece);
});

Dispatched when the size of the board changes. There is a property named newSize in the event.

board.addEventListener("sizeChange", (e) => {
  console.log(e.newSize);
});

MIT