gchessboard

gchessboard is an accessible, customizable and dependency-free chess board web component that can be easily embedded into both vanilla JS and framework-based web applications.

Features:

• Accessible: Supports multiple input modes: click, drag, and keyboard interaction, as well as rudimentary screenreader support.

• Customizable: Almost all styles can be styled using CSS custom properties. This includes piece sets, which can be changed via CSS from the included SVG set. Squares can also show custom content (such as SVGs) using web component slots.

Read more documentation on the website.

Installing

gchessboard is packaged as a Web Component and should be usable directly in most modern browsers. It bundles its own (configurable) styles, inline assets (for chess pieces), and code.

In HTML (using unpkg)

<script type="module" src="https://unpkg.com/gchessboard"></script>

As a module import

First, install from NPM:

npm install gchessboard

Then, in application JS:

import "gchessboard";

Basic usage

<g-chess-board></g-chess-board>

The above example will simply render an empty board. Realistically, though, you would want to use it with some additional attributes set:

<g-chess-board fen="start" interactive></g-chess-board>

The above example sets up a board with the standard chess game start position, and enables interaction using click, drag, and keyboard (by tabbing into the board).

Tutorial and Advanced Examples

• View the tutorial to learn how to use the library and integrate it with chess logic.
• View an example of a computer playing random moves in response to player input, see this Pen.
• The development page (index.html) for this library also includes some advanced setup, including the use of custom slots, event handling, and changing various properties and attributes of the board. See the Developing section for more details.
• The library can be easily wrapped with React. A demo using @lit-labs/react for wrapping is in the mganjoo/react-gchessboard-chessjs-demo repository.
• Another example of an advanced React app leveraging this library is https://knights-tour-game.vercel.app/ (this one uses @microsoft/fast-react-wrapper to wrap the component).

Customizing

More details on properties and attributes of the element, events fired, and various customizable CSS properties are available in the API documentation.

Developing

To start a server that builds the library and serves the demo page index.html and watches for any changes to the filesystem:

npm start

This will create a server and serve on http://localhost:8000/.

Attribution

Chess piece SVG images included in this library were adapted from Category:SVG chess pieces on Wikmedia, with slight optimizations using SVGO.

Original images created by User:Cburnett - Own work, licensed under CC BY-SA 3.0.

Acknowledgements

Some other excellent chessboard libraries that this project is inspired by:

• shaack/cm-chessboard: An ES6 chessboard library, using SVG for rendering. Allows customizing styles and colors of board using CSS.
• justinfagnani/chessboard-element: A web components-based port of the popular chessboardjs library. Uses web component idioms like CustomEvent for various lifecycle events in a move interaction (move start, end, etc).