@echecs/react-board

React chessboard component with drag & drop, animation, and theming. Bundled cburnett piece set, zero external dependencies beyond React.

Live demo

Installation

npm install @echecs/react-board
# or
pnpm add @echecs/react-board

React ≥18 is a peer dependency.

Quick start

Minimal

import { Board } from '@echecs/react-board';

export function App() {
  return <Board />;
}

Full featured

import { useState } from 'react';
import { Board } from '@echecs/react-board';
import type { MoveEvent } from '@echecs/react-board';

const STARTING_FEN = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';

export function ChessGame() {
  const [position, setPosition] = useState(STARTING_FEN);
  const [orientation, setOrientation] = useState<'white' | 'black'>('white');

  function handleMove(event: MoveEvent): boolean {
    // validate and apply move, then update position
    // return false to reject the move
    return true;
  }

  return (
    <div style={{ width: 480 }}>
      <Board
        animate
        coordinates
        orientation={orientation}
        position={position}
        onMove={handleMove}
      />
      <button
        onClick={() =>
          setOrientation((o) => (o === 'white' ? 'black' : 'white'))
        }
      >
        Flip board
      </button>
    </div>
  );
}

Props

| Prop | Type | Default | Description | | --------------- | ------------------------------ | ----------------- | ------------------------------------------------------ | | animate | boolean | true | Enable CSS transition animation on piece moves | | arrows | Arrow[] | — | Arrows to render on the board | | children | React.ReactNode | — | Content rendered inside the board grid | | coordinates | boolean | true | Show rank/file coordinate labels | | highlight | Square[] | [] | Squares to highlight with an overlay | | interactive | boolean | true | Enable drag & drop and click-to-move | | legalMoves | Map<Square, Square[]> | — | Legal move map — restricts user interaction | | onMove | (move: MoveEvent) => boolean | — | Called on every attempted move; return false to reject | | onSquareClick | (square: Square) => void | — | Called when a square is clicked | | orientation | 'white' \| 'black' | 'white' | Which side is at the bottom | | pieces | PieceSet | DEFAULT_PIECES | Custom piece component record | | position | string \| Map<Square, Piece> | starting position | FEN string or position map | | turn | 'white' \| 'black' | — | Restrict interaction to one colour's pieces |

Theming

All visual styling is controlled via CSS custom properties. Set them on a parent element or directly on the board container to override defaults.

.my-board {
  --board-dark-square: #b58863;
  --board-light-square: #f0d9b5;
  --board-highlight: rgba(20, 85, 30, 0.5);
  --board-legal-dot: rgba(0, 0, 0, 0.3);
}

| Variable | Default | Description | | ------------------------------ | ---------------------------------------- | -------------------------------- | | --board-dark-square | #779952 | Dark square colour | | --board-light-square | #edeed1 | Light square colour | | --board-highlight | rgba(255, 255, 0, 0.4) | Highlight overlay colour | | --board-legal-dot | rgba(0, 0, 0, 0.2) | Legal move dot colour | | --board-coordinate-on-light | #779952 | Coordinate text on light squares | | --board-coordinate-on-dark | #edeed1 | Coordinate text on dark squares | | --board-coordinate-weight | 600 | Coordinate font weight | | --board-promotion-background | rgba(0, 0, 0, 0.6) | Promotion dialog background | | --board-drag-shadow | drop-shadow(0 4px 8px rgba(0,0,0,0.4)) | Drag ghost filter | | --board-piece-transition | transform 200ms ease | Piece move animation transition |

Custom pieces

Supply a PieceSet record mapping piece keys to image URLs (any format the browser can render as a CSS background-image — data URIs, SVG files, PNGs):

import { DEFAULT_PIECES } from '@echecs/react-board';
import type { PieceSet } from '@echecs/react-board';

const myPieces: PieceSet = {
  ...DEFAULT_PIECES,
  wP: '/assets/pieces/white-pawn.svg',
};

<Board pieces={myPieces} />;

Piece key format: 'b' | 'w' + 'B' | 'K' | 'N' | 'P' | 'Q' | 'R' (e.g. 'wK' = white king, 'bP' = black pawn).

Sound assets

Bundled move sounds (Lichess standard set, MIT licensed). Import via subpath:

import moveSound from '@echecs/react-board/sounds/move.mp3';
import captureSound from '@echecs/react-board/sounds/capture.mp3';
import castleSound from '@echecs/react-board/sounds/castle.mp3';
import checkSound from '@echecs/react-board/sounds/check.mp3';
import gameEndSound from '@echecs/react-board/sounds/game-end.mp3';

| Subpath export | Description | | ----------------------------------------- | ------------------- | | @echecs/react-board/sounds/move.mp3 | Standard piece move | | @echecs/react-board/sounds/capture.mp3 | Piece capture | | @echecs/react-board/sounds/castle.mp3 | Castling move | | @echecs/react-board/sounds/check.mp3 | Check | | @echecs/react-board/sounds/game-end.mp3 | Game over |

Promotion dialog

PromotionDialog is exported separately for cases where you manage promotion state yourself:

import { PromotionDialog } from '@echecs/react-board';

<PromotionDialog
  color="white"
  squareSize={60}
  onSelect={(piece) => console.log(piece)} // 'q' | 'r' | 'b' | 'n'
  onCancel={() => console.log('cancelled')}
/>;

PromotionDialog props

| Prop | Type | Default | Description | | ------------ | --------------------------------- | ---------------- | ------------------------------- | | color | 'white' \| 'black' | — | Which colour is promoting | | onCancel | () => void | — | Optional. Called when dismissed | | onSelect | (piece: PromotionPiece) => void | — | Called when a piece is clicked | | pieces | PieceSet | DEFAULT_PIECES | Piece component set | | squareSize | number | — | Square size in pixels |

API reference

squareCoords(square, orientation)

Returns { col, row } — 1-based CSS grid coordinates for square given the board orientation.

import { squareCoords } from '@echecs/react-board';

squareCoords('e4', 'white'); // { col: 5, row: 5 }
squareCoords('e4', 'black'); // { col: 4, row: 4 }

Exported types

| Type | Description | | ---------------------- | ---------------------------------------------------------------- | | Arrow | { from: Square; to: Square; brush: string } — arrow descriptor | | BoardProps | All props accepted by <Board /> | | MoveEvent | { from, to, capture, promotion? } — passed to onMove | | PieceKey | Union of all 12 piece keys ('wK', 'bP', …) | | PieceSet | Record<PieceKey, string> — maps piece keys to image URLs | | PromotionDialogProps | All props accepted by <PromotionDialog /> | | PromotionPiece | 'q' \| 'r' \| 'b' \| 'n' — promotable piece | | SquareCoords | { col: number; row: number } — return type of squareCoords |

License

MIT