react-chess-tools

A set of React components for building chess apps

Overview

react-chess-tools is a monorepo containing React components for building chess applications. Built on top of React 19, react-chessboard v5, and chess.js, it provides ready-to-use, customizable components for boards, puzzles, clocks, engine analysis, and browser-based bots.

Packages

Package	Description	Version
@react-chess-tools/react-chess-game	A chess game component with sounds, move highlighting, and keyboard controls
@react-chess-tools/react-chess-puzzle	A chess puzzle component for creating interactive puzzle experiences
@react-chess-tools/react-chess-clock	A standalone chess clock component with multiple timing methods
@react-chess-tools/react-chess-stockfish	Stockfish engine integration with evaluation bar and PV lines
@react-chess-tools/react-chess-bot	Logical CPU players for react-chess-game powered by worker-based engines

Features

• Easy to Use - Simple API with sensible defaults, get started in minutes
• Composition Pattern - Compound component pattern (similar to Radix UI) for maximum flexibility
• asChild Support - Render components as custom elements using the Slot pattern
• Ref Forwarding - Programmatic access to component DOM nodes
• Full HTML Attribute Support - Apply className, style, id, data-, and aria- attributes
• Full-Featured - Built-in sounds, move highlighting, keyboard controls, and more
• Browser Bots - Add configurable CPU players backed by Stockfish or Fairy-Stockfish workers
• TypeScript - Full TypeScript support with comprehensive type definitions
• Modern React - Built for React 19 with hooks and context API

Styling

All components accept standard HTML attributes, making them easy to style with any CSS approach:

Tailwind CSS

import { ChessGame } from "@react-chess-tools/react-chess-game";

function App() {
  return (
    <ChessGame.Root>
      <ChessGame.Board className="rounded-lg shadow-xl border-2 border-gray-300" />
    </ChessGame.Root>
  );
}

CSS Modules / Plain CSS

import { ChessGame } from "@react-chess-tools/react-chess-game";
import styles from "./ChessBoard.module.css";

function App() {
  return (
    <ChessGame.Root>
      <ChessGame.Board className={styles.board} />
    </ChessGame.Root>
  );
}

Inline Styles

<ChessGame.Board
  style={{ borderRadius: "8px", boxShadow: "0 4px 6px rgba(0,0,0,0.1)" }}
/>

Data Attributes

Components expose data attributes for CSS selectors:

[data-clock-active="true"] {
  border-color: gold;
  box-shadow: 0 0 10px gold;
}

Quick Start

Chess Game

npm install @react-chess-tools/react-chess-game

import { ChessGame } from "@react-chess-tools/react-chess-game";

function App() {
  return (
    <ChessGame.Root>
      <ChessGame.Board />
      <ChessGame.Sounds />
      <ChessGame.KeyboardControls />
    </ChessGame.Root>
  );
}

Chess Puzzle

npm install @react-chess-tools/react-chess-game @react-chess-tools/react-chess-puzzle

import { ChessPuzzle } from "@react-chess-tools/react-chess-puzzle";

function App() {
  const puzzle = {
    fen: "r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3",
    moves: ["d2d4", "e5d4", "f3d4"],
    makeFirstMove: false,
  };

  return (
    <ChessPuzzle.Root puzzle={puzzle}>
      <ChessPuzzle.Board />
      <ChessPuzzle.Reset>Restart</ChessPuzzle.Reset>
      <ChessPuzzle.Hint>Get Hint</ChessPuzzle.Hint>
    </ChessPuzzle.Root>
  );
}

Chess Clock

npm install @react-chess-tools/react-chess-clock

import { ChessClock } from "@react-chess-tools/react-chess-clock";

function App() {
  return (
    <ChessClock.Root timeControl={{ time: "5+3" }}>
      <ChessClock.Display color="white" />
      <ChessClock.Display color="black" />
      <ChessClock.PlayPause />
      <ChessClock.Reset>Reset</ChessClock.Reset>
    </ChessClock.Root>
  );
}

Chess Stockfish

npm install @react-chess-tools/react-chess-stockfish

import { ChessStockfish } from "@react-chess-tools/react-chess-stockfish";

function App() {
  return (
    <ChessStockfish.Root
      fen="rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
      workerOptions={{ workerPath: "/stockfish.js" }}
    >
      <ChessStockfish.EvaluationBar showEvaluation />
      <ChessStockfish.EngineLines maxLines={3} />
    </ChessStockfish.Root>
  );
}

Chess Bot

npm install @react-chess-tools/react-chess-game @react-chess-tools/react-chess-stockfish @react-chess-tools/react-chess-bot

import { ChessBot } from "@react-chess-tools/react-chess-bot";
import { ChessGame } from "@react-chess-tools/react-chess-game";

function App() {
  return (
    <ChessGame.Root fen="r1bqkbnr/pppp1ppp/2n5/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 3 3">
      <ChessGame.Board />
      <ChessBot.Player
        color="b"
        strength={{ level: 6 }}
        variability="medium"
        moveDelay={{ min: 250, max: 600 }}
        workerOptions={{ workerPath: "/stockfish.js" }}
      />
    </ChessGame.Root>
  );
}

react-chess-bot depends on @react-chess-tools/react-chess-stockfish for its worker-backed engine integration. It does not bundle an engine worker. Provide your own Stockfish-compatible worker file, and use engineType: "fairy-stockfish" for levels 1-3.

Demo

Visit the Storybook demo to see the packages in action.

Development

This project uses npm workspaces. To get started:

# Install dependencies
npm install

# Build all packages
npm run build

# Run Storybook for development
npm run storybook

# Run tests
npm test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is MIT licensed.

Show Your Support

Give a star if this project helped you!