Chessground: a configurable TypeScript chessboard UI

Chessground's interface and rules boundary

Chessground solves a specific problem: providing the board surface, piece rendering, pointer interaction, animation and visual annotations for a chess application. It was developed for lichess.org, whose browser and Cordova products include analysis boards, puzzles, editors and game previews. The intended users are developers who need a configurable board but already have an application responsible for the game model. That distinction matters. Chessground explicitly contains no chess logic, so it does not decide whether a proposed move is legal, detect checkmate, manage promotion choices or maintain a full game history. A host application must supply those rules and synchronize its state with the board. This boundary makes the package useful for projects that already depend on a rules library, but it also means that installing Chessground alone does not produce a complete chess game.

DOM updates, configuration and interaction flow

The repository describes a custom DOM diff algorithm intended to reduce DOM writes when board state changes. Configuration can be changed at any time, and the board can be resized during its lifetime. CSS classes determine board and piece presentation, including support for 3D boards and pieces. Input handling covers both click-to-move and drag-and-drop. The documented drag behavior includes a minimum distance before dragging begins, centering the piece under the cursor, a ghost element, and either reverting or trashing a drop outside the board. Touchstart, touchmove and touchend are supported for mobile use. The interface can also display the last move, check state, move destinations and premove destinations. User callbacks let the host application observe interactions and decide what its own state should become. Chessground does not use these visual destinations as a substitute for rules. An integrator still needs to validate the requested action and then update the board through the documented API.

FEN, SVG annotations and variant-oriented use

Chessground supports import and export of positions in FEN notation and displays configurable circles, arrows and custom user shapes. The README states that arrows snap to valid moves, while freehand arrows can be drawn by dragging off the board and returning while creating the annotation. Those features are board-interface concerns: the SVG graphics represent information passed to or held by the component, not an independent analysis engine. The explicit lack of chess logic is also what makes variant use possible. A Crazyhouse editor or another custom chess variant can render pieces and capture interaction without forcing the interface to encode the standard game's rules. A document editor can accept newly dragged pieces because board placement and standard move validity are separate operations. The trade-off is additional integration work. The host must define the position, interpret callbacks and distinguish ordinary moves from variant-specific placement or capture operations.

Installing Chessground and initializing a board

The installation command from the README is:

npm install --save @lichess-org/chessground

It installs the published package and records it in the project's npm dependency list. The command does not create a rules engine, a styled page or a complete application.

Creating the first board with the documented API

This example comes directly from the README. It places the board in `document.body` and stores the returned interface as `ground`. With an empty configuration, the board uses the package's documented defaults. The README does not show a complete FEN configuration or callback implementation, so a developer integrating an actual game must consult `src/config.ts`, `src/state.ts` and `src/api.ts` rather than infer property names from this minimal example. It also does not demonstrate adding the linked CSS assets, so the example is initialization code rather than a complete visual application.

import { Chessground } from '@lichess-org/chessground';

const config = {};
const ground = Chessground(document.body, config);

The returned `ground` value is the board interface used by the documented API. A real application would normally configure a position, attach callbacks and provide CSS before presenting the board.

Development builds, tests and the wrong-tool boundary

Repository development uses pnpm 12.9.0 or later, while `package.json` requires Node.js 24 or later. `pnpm install` installs the build dependencies. The compile script invokes `tsc --sourceMap --declaration`; `pnpm run compile --watch` recompiles TypeScript while editing. `pnpm run dist` compiles declarations and JavaScript before bundling `src/chessground.ts` with esbuild into a minified ES module. `pnpm test` runs Vitest once, and `pnpm test:watch` keeps it available for iterative work. Chessground is the wrong choice when a team expects move validation, notation parsing, clocks, promotion dialogs or a complete history from one package. The README is silent about those services because the package intentionally excludes chess logic. It is also not itself a React, Vue, Angular or Svelte component, although the README lists third-party wrappers. A team wanting a complete board application will need more integration than the four-line initialization example provides.

GPL distribution and versioned upgrades

Chessground is published under `GPL-3.0-or-later`. The README states that use for a website can make the combined work subject to GPL distribution requirements and that source code must be released to website users. This is a stated licensing boundary, not legal advice. An organization should examine how the package is bundled, served and combined with its own code before adoption. The repository is not archived, and its last push was on 2026-10-14. Releases include `v10.4.2` on 2026-10-03, `v10.4.1` on 2026-09-29 and `v10.4.0` on 2026-09-27. According to the release procedure, the workflow increments the package version, creates the tag and GitHub release, and publishes to npm. Upgrades therefore require review of type declarations, configuration behavior and asset compatibility rather than assuming a private Lichess UI is being introduced. The package publishes compiled files, declarations, source maps, CSS assets and TypeScript source files. Its lack of runtime dependencies limits transitive supply-chain work, but callers still need to manage their own rules and UI dependencies.

Editorial conclusion

Adopt Chessground when you need a configurable, dependency-free board interface and can meet the GPL-3.0-or-later distribution terms. Do not treat it as a complete chess engine or a ready-made framework component. Before shipping, verify Node.js 24 and pnpm 12 availability, inspect the exported config and API types, and confirm that your application supplies legal moves, notation handling and game-state transitions.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. lichess-org/chessground on GitHub
3. Project website
4. README
5. Releases