A Lightweight, ES6 module based, responsive, mobile friendly SVG chessboard without dependencies. It works on desktop (current versions of Chrome, Firefox, Safari, Edge), and mobile (Android and iOS).
cm-chessboard is the main chessboard of chessmail.eu / chessmail.de, and is used every day by thousands of users.
- Mobile friendly and responsive
- Can handle moves input via click or drag
- Styleable via css
- Uses SVG for rendering
- Vanilla JavaScript modules in ECMAScript 6 syntax
- No dependencies
Option 1: Install the npm package with npm install cm-chessboard
, or
Option 2: Download the code from GitHub and run npm install
.
After installation, copy the cm-chessboard/assets/images/chessboard-sprite.svg
to your projects assets/images
folder.
If you put the sprite somewhere else you have to configure the location in props.sprite.url
.
Preconditions for using cm-chessboard in a web page:
- include the css:
styles/cm-chessboard.css
- import the ES6 module:
import {Chessboard} from "../src/cm-chessboard/Chessboard.js"
Example, showing a FEN:
<script type="module">
import {Chessboard} from "./src/cm-chessboard/Chessboard.js"
new Chessboard(document.getElementById("containerId"),
{ position: "rn2k1r1/ppp1pp1p/3p2p1/5bn1/P7/2N2B2/1PPPPP2/2BNK1RR" })
</script>
Take a look at the /examples folder for more simple examples.
Below is the default configuration
props = {
position: "empty", // set as fen, "start" or "empty"
orientation: COLOR.white, // white on bottom
style: {
cssClass: "default",
showCoordinates: true, // show ranks and files
showBorder: false, // display a border around the board
aspectRatio: 0.9 // height/width. Set to null, if you want to define it only in the css.
},
responsive: false, // resizes the board on window resize, if true
animationDuration: 300, // pieces animation duration in milliseconds
moveInputMode: MOVE_INPUT_MODE.viewOnly, // set to MOVE_INPUT_MODE.dragPiece or MOVE_INPUT_MODE.dragMarker for interactive movement
sprite: {
url: "./assets/images/chessboard-sprite.svg", // pieces and markers are stored as svg in the sprite
grid: 40 // the sprite is tiled with one piece every 40px
}
}
new Chessboard(containerElement, props = {})
containerElement
- a HTML DOM element being the container of the widgetprops
- The board configuration (properties)
Sets a piece on a square. Example: board.setPiece("e4", PIECE.blackKnight)
or
board.setPiece("e4", "bn")
.
Returns a Promise which will be resolved, after the piece is set.
Returns the piece on a square or null
if the square is empty.
Sets the position as fen
. Special values are "start"
, sets the chess start position and
"empty"
, sets an empty board. When animated
is set false
, the new position will be
shown instant.
Returns a Promise which will be resolved, after the Animation has finished.
Returns the board position as fen
.
Adds a marker on a square.
Default types are: MARKER_TYPE.move
, MARKER_TYPE.emphasize
,
exportet by Chessboard.js
. You can create your own marker types: Just create an object like
const myMarker = {class: "my-marker", slice: "marker1"}
, where class
is the css class of the
marker for styling and slice
is the id
in sprite.svg
.
Example for addMarker, getMarkers and removeMarkers
Returns the the board's markers as an array.
Set square to null
, to get all markers of a type on the board. Set type to null
, to get all types.
Set both
to null to get all markers on the board.
Removes markers from the board.
Set square
to null
to remove markers of type
from all squares.
Set type
to null
, to remove all types from a square.
Set both to null
to remove all markers from the board.
Sets the board orientation (color at bottom). Allowed values are COLOR.white
or COLOR.black
.
Returns the the board orientation.
Removes the board from the DOM. Returns a Promise which will be resolved, after destruction.
Enables moves via user input (mouse or touch).
Set optional color
, if you want to enable the move input for a specific side, COLOR.white
or COLOR.black
.
eventHandler
is called on specific events of the user interaction. Receives the parameter event
.
board.enableMoveInput((event) => {
// handle user input here
}, COLOR.white)
The event has the following event.type
:
INPUT_EVENT_TYPE.moveStart
- User started the move input,event.square
contains the coordinatesINPUT_EVENT_TYPE.moveDone
- User finished the move input,event.squareFrom
andevent.squareTo
contain the coordinatesINPUT_EVENT_TYPE.moveCanceled
- User canceled the move with clicking again ob the start square or clicking outside of the board
chessboard.enableMoveInput((event) => {
switch (event.type) {
case INPUT_EVENT_TYPE.moveStart:
console.log(`moveStart: ${event.square}`)
// return `true`, if input is accepted/valid, `false` aborts the interaction, the piece will not move
return true
case INPUT_EVENT_TYPE.moveDone:
console.log(`moveDone: ${event.squareFrom}-${event.squareTo}`)
// return true, if input is accepted/valid, `false` takes the move back
return true
case INPUT_EVENT_TYPE.moveCanceled:
console.log(`moveCanceled`)
}
}, COLOR.white)
Disables moves via user input.
Enables context input (right click on squares).
board.enableContextInput((event) => {
// handle user context input here
})
Example for enableContextInput
event.square
contains the coordinates of the user input.
Disables the context input.
There exists a ticket from someone who is using cm-chessboard with react: shaack#20
- License for the code: MIT
- License for the SVG-pieces: CC BY-SA 3.0