{"id":21076110,"url":"https://github.com/shaack/cm-chessboard","last_synced_at":"2025-05-15T09:08:12.612Z","repository":{"id":37677880,"uuid":"111542366","full_name":"shaack/cm-chessboard","owner":"shaack","description":"A JavaScript chessboard without dependencies. Rendered in SVG, coded in ES6. Views FEN, handles move input, animated, responsive, expandable","archived":false,"fork":false,"pushed_at":"2025-03-16T13:30:37.000Z","size":1127,"stargazers_count":243,"open_issues_count":6,"forks_count":70,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-09T18:29:43.503Z","etag":null,"topics":["chess","chess-board","chessboard","chessmail","ecmascript6","es6","frontend","javascript","released","ui"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shaack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-21T11:50:10.000Z","updated_at":"2025-04-25T09:27:04.000Z","dependencies_parsed_at":"2023-09-26T11:51:07.290Z","dependency_job_id":"c83b823b-3a8d-4016-a8f7-4be23776f932","html_url":"https://github.com/shaack/cm-chessboard","commit_stats":{"total_commits":1259,"total_committers":12,"mean_commits":"104.91666666666667","dds":"0.018268467037331204","last_synced_commit":"09fa14255ea06194aa9906258142da8f8234eaec"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaack%2Fcm-chessboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaack%2Fcm-chessboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaack%2Fcm-chessboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaack%2Fcm-chessboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shaack","download_url":"https://codeload.github.com/shaack/cm-chessboard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310520,"owners_count":22049470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chess","chess-board","chessboard","chessmail","ecmascript6","es6","frontend","javascript","released","ui"],"created_at":"2024-11-19T19:26:41.370Z","updated_at":"2025-05-15T09:08:07.596Z","avatar_url":"https://github.com/shaack.png","language":"JavaScript","readme":"# cm-chessboard\n\nA JavaScript chessboard which is lightweight, ES6 module based, responsive, SVG rendered and **without dependencies**.\n\ncm-chessboard is the main chessboard of\n[chessmail.eu](https://www.chessmail.eu) and [chessmail.de](https://www.chessmail.de). It is also used\nin [chess-console](https://shaack.com/projekte/chess-console/examples/load-pgn.html) and in\n[cm-fen-editor](https://shaack.com/projekte/cm-fen-editor/). They are all nice written ES6 Modules to handle different aspects of chess games.\n\n## Features\n\n- **No dependencies**, just clean ES6\n- [Can handle moves input via click or drag](https://shaack.com/projekte/cm-chessboard/examples/validate-moves.html)\n- [Styleable via css and supports multiple piece sets](https://shaack.com/projekte/cm-chessboard/examples/different-styles.html)\n- Uses SVG for rendering\n- [Allows adding extensions to extend the\nfunctionality](https://shaack.com/projekte/cm-chessboard/examples/extensions/arrows-extension.html)\n\n## Extensions\n\nThe core of cm-chessboard is small, fast and reduced to the essentials. You can easily extend its functionality with extensions.\n\n- [Markers Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/markers-extension.html) ⇨ create markers on specific squares\n- [Arrows Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/arrows-extension.html) ⇨ renders arrows on the chessboard\n- [Accessibility Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/accessibility-extension.html) ⇨ makes the chessboard more accessible\n- [PromotionDialog Extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/promotion-dialog-extension.html) ⇨ shows a dialog to select the piece to promote to\n\n## Demo and repository\n\n- **Demo: [http://shaack.com/projekte/cm-chessboard/](https://shaack.com/projekte/cm-chessboard/)**\n- **Repository: [https://github.com/shaack/cm-chessboard](https://github.com/shaack/cm-chessboard)**\n\n![Example chessboards](https://shaack.com/projekte/assets/img/example_chessboards_staunty.png?v=2)\n\n## Installation and first steps\n\n### Step 1: Install the package\n\n- **Option 1:** Install the [npm package](https://www.npmjs.com/package/cm-chessboard) with `npm install cm-chessboard`.\n- **Option 2:** Download the code from [GitHub](https://github.com/shaack/cm-chessboard).\n- **Option 3:** Use it via CDN https://cdn.jsdelivr.net/npm/cm-chessboard@8/src/Chessboard.js\n\n### Step 2: Create your cm-chessboard page\n\n#### Step 2a: Include the CSS file\n\n```html\n\u003clink rel=\"stylesheet\" href=\"./node_modules/cm-chessboard/assets/styles/cm-chessboard.css\"\u003e\n```\n\n- Some extensions, like \"[Markers](https://shaack.com/projekte/cm-chessboard/examples/extensions/markers-extension.html)\", \"[Promotion Dialog](https://shaack.com/projekte/cm-chessboard/examples/extensions/promotion-dialog-extension.html)\" or \"[Arrows](https://shaack.com/projekte/cm-chessboard/examples/extensions/arrows-extension.html)\" need additional CSS. See the examples.\n\n#### Step 2b: Create a container for the chessboard\n\n```html\n\u003cdiv id=\"board\"\u003e\u003c/div\u003e\n```\n\n#### Step 2c: Create the chessboard in your JavaScript code.\n\n```html\n\n\u003cscript type=\"module\"\u003e\n  import {Chessboard, FEN} from \"./path/to/Chessboard.js\"\n\n  const board = new Chessboard(document.getElementById(\"board\"), {\n    position: FEN.start,\n    assetsUrl: \"./path/to/assets/\" // wherever you copied the assets folder to, could also be in the node_modules folder\n  })\n\u003c/script\u003e\n```\n\nYou need to configure the `assetsUrl` in your chessboard props (the second parameter). The `assetsUrl` must be the path to the `assets` folder of this project, where the pieces SVGs and other resources are located. \n\nYou can also copy the `assets` folder from `cm-chessboard/assets` to your project and modify the content.\n\n#### See also\n\n- [Simple cm-chessboard example online](https://shaack.com/projekte/cm-chessboard/examples/simple-boards.html)\n\n### Step 3: (Optional) Enable user input\n\nTo enable the user to move the pieces, you have to enable the move input.\n\n```javascript\nconst board = new Chessboard(document.getElementById(\"board\"), {\n        position: FEN.start,\n        assetsUrl: \"../assets/\",\n        extensions: [{class: Markers}] // Looks better with markers. (Don't forget to also include the CSS for the markers)\n    })\n\n    board.enableMoveInput(inputHandler) // This enables the move input\n\n    function inputHandler(event) {\n        console.log(event)\n        if(event.type === INPUT_EVENT_TYPE.moveInputStarted || \n                event.type === INPUT_EVENT_TYPE.validateMoveInput) {\n            return true // false cancels move\n        }\n    }\n```\n\n#### See also\n\n- [Simple example with move input enabled](https://shaack.com/projekte/cm-chessboard/examples/enable-input.html)\n- [More complex example with move validation](https://shaack.com/projekte/cm-chessboard/examples/validate-moves.html)\n\nTake a look at the [/examples](https://github.com/shaack/cm-chessboard/tree/master/examples) folder for more examples.\n\n## Configuration\n\nBelow is the default configuration\n\n```javascript\nthis.props = {\n    position: FEN.empty, // set position as fen, use FEN.start or FEN.empty as shortcuts\n    orientation: COLOR.white, // white on bottom\n    responsive: true, // resize the board automatically to the size of the context element\n    assetsUrl: \"./assets/\", // put all css and sprites in this folder, will be ignored for absolute urls of assets files\n    assetsCache: true, // cache the sprites, deactivate if you want to use multiple pieces sets in one page\n    style: {\n        cssClass: \"default\", // set the css theme of the board, try \"green\", \"blue\" or \"chess-club\"\n        showCoordinates: true, // show ranks and files\n        borderType: BORDER_TYPE.none, // \"thin\" thin border, \"frame\" wide border with coordinates in it, \"none\" no border\n        aspectRatio: 1, // height/width of the board\n        pieces: {\n            type: PIECES_FILE_TYPE.svgSprite, // pieces are in an SVG sprite, no other type supported for now\n            file: \"pieces/standard.svg\", // the filename of the sprite in `assets/pieces/` or an absolute url like `https://…` or `/…`\n            tileSize: 40 // the tile size in the sprite\n        },\n        animationDuration: 300 // pieces animation duration in milliseconds. Disable all animations with `0`\n    },\n    extensions: [ /* {class: ExtensionClass, props: { ... }} */] // add extensions here\n}\n```\n\n## API\n\n### constructor\n\n`new Chessboard(context, props = {})`\n\n- **`context`**: the HTML DOM element being the container of the widget\n- **`props`**: The board configuration (properties)\n\n### setPiece(square, piece, animated = false)\n\nSets a piece on a square. Example: `board.setPiece(\"e4\", PIECE.blackKnight, true)` or\n`board.setPiece(\"e4\", \"bn\")`. Remove a Piece with `board.setPiece(\"e4\", null)`. Returns a **Promise**, which is\nresolved,\nafter the animation finished.\n\n### getPiece(square)\n\nReturns the piece on a square or `null` if the square is empty.\n\n### movePiece(squareFrom, squareTo, animated = false)\n\nMove a piece from `squareFrom` to `squareTo`. Returns a **Promise**, which is resolved, after the animation finished.\n\n[Example for **movePiece**](https://shaack.com/projekte/cm-chessboard/examples/pieces-animation.html)\n\n### setPosition(fen, animated = false)\n\nSets the position as `fen` or only the position part of a `fen`. Returns a **Promise**, which is resolved, after the animation finished.\n\n[Example for **setPosition**](https://shaack.com/projekte/cm-chessboard/examples/pieces-animation.html)\n\n### getPosition()\n\nReturns the board position in form of the position part of a `fen`.\n\n### setOrientation(color)\n\nSets the board orientation (color at bottom). Allowed values are `COLOR.white` or `COLOR.black`.\n\n[Example for **setOrientation**](https://shaack.com/projekte/cm-chessboard/examples/enable-input.html)\n\n### getOrientation()\n\nReturns the board orientation.\n\n### destroy()\n\nRemoves the board from the DOM.\n\n[Example for **destroy**](https://shaack.com/projekte/cm-chessboard/examples/destroy-many-boards.html)\n\n### enableMoveInput(eventHandler, color = undefined)\n\nEnables moves via user input (mouse or touch). Set optional `color`, if you want to enable the move input for a specific\nside, `COLOR.white` or `COLOR.black`.\n\n`eventHandler` is called on specific events of the user interaction. Receives the parameter `event`.\n\n```javascript\nboard.enableMoveInput((event) =\u003e {\n    // handle user input here\n}, COLOR.white)\n```\n\n[Example for **enableMoveInput**](http://shaack.com/projekte/cm-chessboard/examples/enable-input.html)\n\nThe event has the following **`event.type`**:\n\n- **`INPUT_EVENT_TYPE.moveInputStarted`**: User started the move input, `event.squareFrom` contains the coordinates.\n  Return `true` or `false` to validate the start square. `false` cancels the move.\n- **`INPUT_EVENT_TYPE.validateMoveInput`**: To validate the users move input. `event.squareFrom` and `event.squareTo`\n  contain the coordinates. Return `true` or `false` to validate the move. `false` cancels the move.\n- **`INPUT_EVENT_TYPE.moveInputCanceled`**: The user canceled the move with clicking again on the start square, clicking\n  outside the board or right click.\n- **`INPUT_EVENT_TYPE.moveInputFinished`**: Fired after the move was made, also when canceled.\n- **`INPUT_EVENT_TYPE.movingOverSquare`**: Fired, when the user moves the piece over a square. `event.squareTo` contains\n  the coordinates.\n\n```javascript\nchessboard.enableMoveInput((event) =\u003e {\n    console.log(\"move input\", event)\n  switch (event.type) {\n      case INPUT_EVENT_TYPE.moveInputStarted:\n          console.log(`moveInputStarted: ${event.squareFrom}`)\n          return true // false cancels move\n      case INPUT_EVENT_TYPE.validateMoveInput:\n          console.log(`validateMoveInput: ${event.squareFrom}-${event.squareTo}`)\n          return true // false cancels move\n      case INPUT_EVENT_TYPE.moveInputCanceled:\n          console.log(`moveInputCanceled`)\n          break\n      case INPUT_EVENT_TYPE.moveInputFinished:\n          console.log(`moveInputFinished`)\n          break\n      case INPUT_EVENT_TYPE.movingOverSquare:\n          console.log(`movingOverSquare: ${event.squareTo}`)\n          break\n  }\n}, COLOR.white)\n```\n\n### disableMoveInput()\n\nDisables moves via user input.\n\n## Piece sets\n\ncm-chessboard supports alternative piece sets. A piece set is defined in an SVG sprite. cm-chessboard is shipped with\ntwo sets, the default [staunty](https://github.com/ornicar/lila/tree/master/public/piece/staunty) (\nchessboard-sprite-staunty.svg) and a sprite of the\n[Wikimedia standard pieces](https://commons.wikimedia.org/wiki/Category:SVG_chess_pieces/Standard)\n(chessboard-sprite.svg).\n\nSprites must be 40x40px in size where the piece elements must have ids like\n\"bp\" (black pawn) or \"wq\" (white queen). Just open the sprite in a text editor, SVG is readable like HTML.\n\n## Extensions\n\ncm-chessboard provides the ability to extend its functionality with extensions. Extensions extend the class `Extension`\nand have access to the chessboard and can register extension points.\n\n### registerExtensionPoint(name, callback)\n\n```js\nclass MyCoolChessboardExtension extends Extension {\n    constructor(chessboard, props) {\n        super(chessboard, props)\n        this.registerExtensionPoint(EXTENSION_POINT.moveInput, (data) =\u003e {\n            // do something on move [start | cancel | done]\n            console.log(data)\n        })\n    }\n}\n```\n\nCurrently possible extension points are defined in `Extension.js`.\n\n```js\nexport const EXTENSION_POINT = {\n    positionChanged: \"positionChanged\", // the positions of the pieces was changed\n    boardChanged: \"boardChanged\", // the board (orientation) was changed\n    boardResized: \"boardResized\", // the board was resized\n    moveInputToggled: \"moveInputToggled\", // move input was enabled or disabled\n    moveInput: \"moveInput\", // move started, moving over a square, validating or canceled\n    beforeRedrawBoard: \"beforeRedrawBoard\", // called before redrawing the board\n    afterRedrawBoard: \"afterRedrawBoard\", // called after redrawing the board\n    animation: \"animation\", // called on animation start, end and on every animation frame\n    destroy: \"destroy\" // called, before the board is destroyed\n}\n```\n\nEnable extensions via the chessboard props.\n\n```js\nconst chessboard = new Chessboard(document.getElementById(\"board\"), {\n    position: FEN.start,\n    extensions: // list of used extensions\n        [{\n            class: MyCoolChessboardExtension, // the class of the extension\n            props: {\n                // configure the extension here\n            }\n        }]\n})\n```\n\n### Add methods to the chessboard\n\nAdd methods to the chessboard in the constructor of your extension like shown below.\n\n```js\n  chessboard.addMarker = this.addMarker.bind(this)\n```\n\n## The main extensions contained in cm-chessboard\n\n### Markers extension\n\nCreates markers on the board. Example: [Markers extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/markers-extension.html)\n\nSee the [README](src/extensions/markers/README.md) of the Markers. extension.\n\n### Arrows extension\n\nDraw arrows on the board. Example: [Arrows extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/arrows-extension.html)\n\n#### Methods\n\n##### addArrow(type, fromSquare, toSquare)\n\nAdd an arrow.\n\n##### removeArrows(type, from, to)\n\nTo remove all arrows, call `chessboard.removeArrows()` without parameters. To remove all arrows of a specific\ntype (type \"danger\"), call `chessboard.removeArrows(ARROW_TYPE.danger)`. To remove all arrows starting at \"\ne2\"\nyou can call `chessboard.removeArrows(undefined, \"e2\")` and so on...\n\n##### getArrows(type, from, to)\n\nTo get all arrows, call `chessboard.getArrows()` without parameters, as with `removeArrows(type, from, to)`.\n\n### Accessibility Extension\n\nThis extension ensures that visual impaired people can better use the chessboard. It displays the braille notation\nof the current position in the alt tag of the board image and enables a form to move the pieces via text input. It\ncan also display the board as HTML table and the pieces as list.\n\nSee the example [Accessibility extension](https://shaack.com/projekte/cm-chessboard/examples/extensions/accessibility-extension.html)\n\n#### Usage\n\n```js\nconst chessboard = new Chessboard(document.getElementById(\"board\"), {\n    position: FEN.start,\n    sprite: {url: \"../assets/images/chessboard-sprite.svg\"},\n    // animationDuration: 0, // optional, set to 0 to disable animations\n    style: {\n        cssClass: \"default-contrast\" // make the coordinates better visible with the \"default-contrast\" theme\n    },\n    extensions:\n        [{\n            class: Accessibility,\n            props: {\n                brailleNotationInAlt: true, // show the braille notation of the position in the alt attribute of the SVG image\n                boardAsTable: true, // display the board additionally as HTML table\n                movePieceForm: true, // display a form to move a piece (from, to, move)\n                piecesAsList: true, // display the pieces additionally as List\n                visuallyHidden: false // hide all those extra outputs visually but keep them accessible for screen readers and braille displays\n            }\n\n        }]\n})\n```\n\n\n## Usage with JS Frameworks\n\n- Works with **Vue** out of the box\n- Works with **Svelte** out of the box\n- I don't use **React**, but there exists a ticket from someone who is using cm-chessboard with\n  react: https://github.com/shaack/cm-chessboard/issues/20\n- It should work also with **all other JS frameworks**, because cm-chessboard is written in standard ES6 and has **no\n  dependencies**.\n\n## Licenses\n\n- License for the code: [MIT](https://github.com/shaack/cm-chessboard/blob/master/LICENSE)\n- License for the Staunty SVG-pieces (\n  chessboard-sprite-staunty.svg): [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)\n- License for the Wikimedia SVG-pieces (\n  chessboard-sprite.svg): [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/)\n\n---\n\nFind more high quality JavaScript modules from [shaack.com](https://shaack.com)\non [our projects page](https://shaack.com/works).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshaack%2Fcm-chessboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshaack%2Fcm-chessboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshaack%2Fcm-chessboard/lists"}