chessboard-kit

Modern, strongly typed chessboard UI for the web. DOM-based rendering, SVG boards and pieces, smooth move animation, keyboard access, and a small publishable footprint.

Overview

chessboard-kit is a production-ready TypeScript chessboard library inspired by chessboard.js, but designed with a cleaner API and modern architecture.

It uses regular DOM elements instead of canvas, keeps the rendering tree-shakeable, and ships with built-in board themes plus a default SVG chess piece set sourced from the assets in this repository.

Features

• Responsive board sizing
• Drag-and-drop moves
• Click-to-move interaction
• Touch support
• Board flipping
• Coordinates
• FEN load and save
• PGN loading
• Board resize handling
• Move animation
• Last-move highlighting
• Selected-square styling
• Legal-move highlighting
• Custom square styling hooks
• Promotion callback
• Event system
• destroy(), setPosition(), move(), clear(), reset()
• Keyboard navigation and ARIA labels

Install

npm install chessboard-kit

Import

import { Chessboard } from 'chessboard-kit';
import 'chessboard-kit/style.css';

Quick Start

import { Chessboard } from 'chessboard-kit';
import 'chessboard-kit/style.css';

const board = new Chessboard('#board', {
  theme: 'classicWood',
  pieces: 'default',
  orientation: 'white',
  draggable: true,
  coordinates: true,
  animation: true,
  fen: 'start',
});

board.move('e2', 'e4');
board.flip();
board.loadFEN('start');
console.log(board.getFEN());
board.destroy();

API at a Glance

const board = new Chessboard('#board', options);

board.move('e2', 'e4');
board.flip();
board.setTheme('green');
board.setPieceSet('default');
board.loadFEN(fen);
board.loadPGN(pgn);
board.setPosition('start');
board.clear();
board.reset();
board.destroy();

Options

| Option | Type | Description | | ----------------- | ---------------- | --------------------------------------- | | theme | string | Built-in or custom board theme | | pieces | string | Built-in or custom piece set | | orientation | white \| black | Initial board orientation | | draggable | boolean | Enable drag-and-drop moves | | coordinates | boolean | Show board coordinates | | animation | boolean | Enable move animation | | fen | string | Initial FEN, or start | | position | string | Alias for initial FEN | | showLegalMoves | boolean | Highlight legal targets after selection | | squareClassName | function | Add custom square classes | | squareStyle | function | Add custom square styles |

Events

The library exposes both callback props and an event emitter style API.

Supported events:

• onMove
• onDrop
• onDragStart
• onDragEnd
• onSquareClick
• onPositionChange
• onBoardFlip
• onPromotion

Example:

const board = new Chessboard('#board', {
  onMove: (event) => {
    console.log(event.from, event.to, event.san);
  },
  onPromotion: () => 'q',
});

board.on('positionchange', (event) => {
  console.log(event.fen);
});

Themes

The package automatically registers these built-in board themes:

• classicWood
• blue
• green
• dark
• tournamentMarble

Switch themes at runtime:

board.setTheme('green');

Register a custom theme:

import { registerBoardTheme } from 'chessboard-kit';

registerBoardTheme(
  'midnight',
  'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 8 8"></svg>',
);

See docs/theme-guide.md for the full guide.

Pieces

The supplied SVG piece set is registered as the default piece set.

board.setPieceSet('default');

Register a custom piece set:

import { registerPieceSet } from 'chessboard-kit';

registerPieceSet('minimal', {
  white_king: '/pieces/white-king.svg',
  white_queen: '/pieces/white-queen.svg',
  white_rook: '/pieces/white-rook.svg',
  white_bishop: '/pieces/white-bishop.svg',
  white_knight: '/pieces/white-knight.svg',
  white_pawn: '/pieces/white-pawn.svg',
  black_king: '/pieces/black-king.svg',
  black_queen: '/pieces/black-queen.svg',
  black_rook: '/pieces/black-rook.svg',
  black_bishop: '/pieces/black-bishop.svg',
  black_knight: '/pieces/black-knight.svg',
  black_pawn: '/pieces/black-pawn.svg',
});

See docs/custom-piece-guide.md for a full example.

Public Methods

| Method | Description | | ----------------------------- | ------------------------------------ | | move(from, to, promotion?) | Make a move programmatically | | flip() | Flip the board orientation | | setOrientation(orientation) | Set the board orientation explicitly | | setTheme(name) | Change the active board theme | | setPieceSet(name) | Change the active piece set | | loadFEN(fen) | Load a FEN position | | getFEN() | Read the current FEN | | loadPGN(pgn) | Load a PGN string | | setPosition(position) | Set the board position | | clear() | Remove all pieces from the board | | reset() | Restore the starting position | | destroy() | Tear down the board and listeners | | on(event, handler) | Subscribe to events | | off(event, handler) | Remove an event listener |

Accessibility

chessboard-kit includes keyboard navigation, focus states, and ARIA labels so the board can be used without drag-and-drop alone.

Examples

• Vanilla JavaScript
• TypeScript
• React
• Vue
• Angular
• Svelte

Documentation

• API documentation
• Theme guide
• Custom piece guide
• Example screenshots
• npm publishing guide

Development

npm install
npm run typecheck
npm run test
npm run build
npm run lint

Package Output

The package is configured for:

• ESM and CommonJS builds
• Type declaration output
• CSS export via chessboard-kit/style.css
• Tree-shakeable public entrypoints

License

MIT