react-chessboard: a board component that leaves the game rules to chess.js

Presentation and interaction, with the rules deliberately left out

react-chessboard is a modern, responsive chessboard component for React applications, and the description is the whole scope of the project.

What that means is worth being precise about, because the topic tags include chessjs and a reader might expect the board to know the rules of chess. It does not. The component renders a board, lets you drag pieces, reports what happened, and leaves move legality and game state to a separate library. The topic list includes chess, chessjs, drag-and-drop, react and reactjs, and it is the drag-and-drop and the board that this project implements.

The feature list is a list of interface capabilities. Drag and drop. Custom pieces. Spare pieces, which is the captured-pieces tray beside the board. Custom styling. Animation. Custom board dimensions. Event handling. Mobile support. Responsive layout. Accessibility. TypeScript support. And helpful utility functions.

Several of those are more than they sound. Custom board dimensions means the board is not fixed at eight files, which matters for variants or for teaching boards at a smaller size. Spare pieces means the component can display and let you interact with the captured pieces, which is the visible history of the game. Animation means a move plays out rather than teleporting. Accessibility is listed as its own item, and it is the one the project is still reviewing, as the contribution list says.

The Quick Start makes the shape concrete.

import { Chessboard } from 'react-chessboard';

function App() {
  const chessboardOptions = {
    // your config options here
  };

  return <Chessboard options={chessboardOptions} />;
}

So the public API is a single component with an options object. There is no chess state in the props, no onMove that validates, and no game object. You pass configuration, you handle events, and you own the position.

The homepage is react-chessboard.vercel.app, which is also where the documentation lives, and the primary language is TypeScript. The licence is MIT with LICENSE at the root and the copyright line naming Ryan Gregory.

dnd-kit does the dragging, and the two runtime dependencies are the point

The dependency list is short in a way that says something about the design.

The runtime dependencies are @dnd-kit/core at 6.3.1 and @dnd-kit/modifiers at 9.0.0. That is the entire production dependency list.

dnd-kit is the drag and drop library that replaced the older HTML5-based approach to interactive drag and drop in React. It is a headless library: it gives you the sensors, the drag context and the droppable registration, and leaves the rendering entirely to you. That matters for this component, because a chessboard needs to drag a piece image onto a square, and the piece needs to animate back to its origin when a drop is rejected. A headless drag library gives you control over exactly that.

The modifiers package is what makes the constrained behaviour possible, and the constraint in a chessboard is real: a piece can only move onto a legal square, and in many implementations only onto squares the rules allow. dnd-kit's modifiers are the mechanism for restricting where a dragged item may be dropped.

So the component does not implement dragging itself. It implements the chessboard-specific parts: how a piece looks, how a square looks, how a move is reported, how the board is sized and styled, and how the animation and accessibility behaviour work. The generic interaction problem is delegated.

Two runtime dependencies is also a good sign for a component that other people embed in their own applications. There is no state management library, no styling framework, no icon set and no chess rules engine in the tree. Everything you see on the page is either the component's own code or dnd-kit.

For the reader who wants to know why the README lists TypeScript support and the package ships types, the manifest is explicit about it. The types entry is dist/index.d.ts, the package is type module, and the exports map publishes types, an import entry and a require entry.

  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.esm.js",
      "require": "./dist/index.js"
    }
  },

So the package ships both a CommonJS and an ES module build with a single conditional export map, which is the shape that lets a bundler pick the right one and a TypeScript consumer get the right declaration file.

The build is Rollup, the releases are semantic, and the version field is a placeholder

The build and release tooling tells you how the library is put together and how it moves.

The build script is rimraf dist && rollup -c, and the rollup plugins in the dev dependencies are the commonjs, node-resolve and typescript ones. So the library is bundled with Rollup from TypeScript sources, with the TypeScript plugin emitting declarations along the way.

There are two tsconfig files, tsconfig.json and tsconfig.build.json, which is the usual split between the development configuration that includes tests and the build configuration that produces the published output.

The version field in the manifest is 0.0.0-semantically-released, and the release.config.mjs file at the root is what replaces it. That is a semantic-release convention: the version in the repository is a placeholder and the real version is computed from the commit history at release time. The release tags in the repository confirm it, with v5.12.1 on 2026-08-16, v5.12.0 on 2026-08-03 and v5.11.0 on 2026-08-01. Three releases in a fortnight.

The commit history is enforced by tooling. There is a commitlint.config.mjs at the root, a commitlint script, and @commitlint/config-conventional in the dev dependencies, so commit messages follow the conventional commits format and the version bump follows from them.

Quality gates are visible too. The test:static script is tsc && eslint src docs && prettier --check src docs, which is a type check, a lint and a formatting check over both the source and the documentation. The format script applies eslint --fix and prettier --write over the same two directories.

There is a .husky/ directory and a prepare script that runs husky, so the commit hooks are installed on install rather than by each contributor manually.

The one thing the package.json does not show is a unit test suite. The scripts are test:static, which is type checking and linting, and there is no test runner in the dependency list. The contribution list makes that explicit: the request is to add a test suite full of unit tests for utils and all options stories, and visual tests. So the library currently relies on TypeScript, lint and formatting as its automated checks, and the Storybook stories plus the documentation site are the primary way to verify behaviour by hand.

Storybook is where the options are actually documented

The .storybook/ directory and the storybook scripts are the centre of this project, and they say something about how a component with this many options gets documented.

The scripts are storybook dev -p 6006 for development and storybook build for a static build. The dev dependencies include @storybook/addon-docs, addon-essentials, addon-interactions and blocks, plus @chromatic-com/storybook at version 3.

The addons tell you what kind of documentation this is. addon-docs generates documentation from the component's types and doc comments, addon-essentials gives the standard controls panel and viewport tools, addon-interactions provides the play-function testing surface, and blocks gives the markdown documentation components. Chromatic is the visual regression service, and its presence alongside a build-storybook script means the components are published and compared visually on change.

So the story files are effectively the API reference. A component like this has a large options object, and every option is a story with a control, a description and a rendered result. That is a better fit than a prose API table, because the reader sees the option's effect rather than reading about it, and it doubles as the manual test surface.

The documentation site lives at react-chessboard.vercel.app and the README points at it for detailed documentation, examples and the API reference. The contribution guide is hosted there too, under a path that names it the developers guide for the project.

The contribution list also tells you what the maintainers think is missing, and that is unusually useful information. There are two feature items and one documentation item.

The first feature item is drag and drop enhancements: add a dropAnimation prop to allow override of the DragOverlay dropAnimation prop that is currently set to null, so a drag overlay can be animated back to its position on failed drops instead of snapping back.

That single sentence describes a concrete behaviour gap in the current release. The drag overlay's drop animation is set to null today, so a rejected drop is instant rather than animated. If you are building an interface where a rejected move should feel considered, that is the option that is not there yet.

The second feature item is accessibility improvements: review and enhance sensor implementations and accessibility. The word sensor here refers to the dnd-kit sensors, the set of input devices the drag layer listens to, so the accessibility work is about making sure the board can be operated by keyboard and assistive technology rather than by pointer drag alone.

The documentation item is framework integrations: add framework specific documentation for Next.js, Vite and Remix, with the example given being the use client directive at the top of the component consuming the Chessboard component. That is a real and easy-to-miss requirement, because the library ships as an ES module with client-side behaviour and a Next.js application server rendering the page needs to opt that component into the client.

Where react-chessboard is the wrong tool

The first wrong-tool case is a developer who wants one package to give them a working chess game. The board does not know the rules. You need a second library for move legality, position state and notation, and chessjs is the obvious candidate given the topic tags. If you expected the component to accept a position and enforce legal moves, that expectation will not be met, and the integration work is where the complexity moves rather than disappears.

The second case is a server-rendered React application that has not dealt with the client boundary. The package publishes an ES module build and the library uses browser APIs for dragging, so in a Next.js application the consuming component needs the use client directive. The README's own contribution list flags this as documentation still to be written, which tells you it is a live source of confusion rather than a solved problem.

The third case is a project that needs a board with a different game on it. The component's vocabulary is chess. Spare pieces, promotion, castling rights and a board that can be sized differently are all chess concepts, and adapting it to a different game means fighting the option names rather than reusing them.

The fourth case is a team that needs proven automated test coverage today. There is no test runner in the dependency list, and the contribution list asks for a unit test suite and visual tests as work still to be done. The Storybook stories and the Chromatic visual comparison cover the components, but there is no automated assertion layer over the utility functions that the feature list calls helpful utility functions.

On the ecosystem question, the alternatives are worth placing side by side. The older generation of React chessboard components generally bundled the rules engine with the board, so you got move validation for free and could not swap it out. The newer approach, which this project takes, separates the two and lets you compose a rules library, a board library and your own state management. The trade is real: the separated design gives you freedom and a smaller dependency tree, at the cost of more wiring and more of the rules living in your application rather than in the component.

There is one more practical point about the drop animation that is worth flagging for a project that cares about feel. A failed drop currently snaps the piece back rather than animating it, because the DragOverlay dropAnimation prop is set to null, and the prop to override that is on the contribution list rather than in the release. That is a small thing, but on a board where a rejected move is common, it is the difference between an interface that explains itself and one that appears to drop pieces.

On licence, MIT with a LICENSE file at the root and the copyright line naming Ryan Gregory, which permits commercial use and modification with no copyleft obligation, so dropping this into a product application raises no licensing question.

Editorial conclusion

react-chessboard suits a React developer who needs a chessboard interface and already has, or wants, a separate rules engine such as chess.js, because the component's whole scope is presentation and interaction and the two libraries compose without fighting. It does not suit someone who wants one package that also validates moves and tracks the position, because that logic is not in here. Before adopting, check the documented options for the pieces and board styling you need, and note that the drop animation is currently set to null, so a failed drop snaps the piece back rather than animating it.

Frequently asked questions

Official sources

1. Clariity/react-chessboard on GitHub
2. License: MIT
3. Project website
4. README
5. Releases