react-chess // feature-rich chess board for React

//00api_reference

API Reference

Complete component documentation with interactive examples. Toggle any prop and see the board update in real time.

Interactive Playground

Toggle props and watch the board update live. The generated code below stays in sync.

Appearance

Theme

Orientation

Layout & Display

Layout

showMoveHistoryshowNavigationshowBoardControlsshowCoordinates

Behavior

Load PGNautoPromoteToQueenenableKeyboardNavigation

<Chessboard
  width={320}
  height={320}
  theme="brown"
  orientation="white"
  layout="horizontal"
  pgn="..."
  showMoveHistory={true}
  showNavigation={true}
  showBoardControls={true}
  showCoordinates={true}
  autoPromoteToQueen={false}
  enableKeyboardNavigation={true}
  onMove={(from, to, move) => {
    console.log(move.san);
  }}
/>

Chessboard

All-in-one convenience component. Wraps ChessProvider, Board, MoveHistory, Navigation, and BoardControls into a single element with a flat prop API.

import { Chessboard } from "@mdwebb/react-chess";
import "@mdwebb/react-chess/styles";

<Chessboard
  width={500}
  height={500}
  theme="brown"
  showMoveHistory={true}
  showNavigation={true}
  onMove={(from, to, move) => console.log(move.san)}
/>

Prop	Type	Default	Description
width	string \| number	"400px"	Board width
height	string \| number	"400px"	Board height
theme	ChessboardTheme	"brown"	Theme preset name or custom theme object
orientation	PieceColor	"white"	Board orientation: "white" or "black"
layout	ChessboardLayout	"horizontal"	Layout: "horizontal", "vertical", or "board-only"
fen	string	"start"	FEN string for initial position
pgn	string	—	PGN string to load a game
showMoveHistory	boolean	false	Display the move history panel
showNavigation	boolean	false	Display navigation buttons (First/Prev/Next/Last)
showBoardControls	boolean	false	Display board control buttons (flip, reset)
showCoordinates	boolean	true	Show a–1h / 1–8 coordinate labels
moveHistoryWidth	string \| number	"300px"	Width of the move history panel
autoPromoteToQueen	boolean	false	Auto-promote pawns to queen without dialog
enableKeyboardNavigation	boolean	true	Enable arrow key / Home / End navigation
draggable	Config['draggable']	—	Chessground draggable configuration pass-through
movable	Config['movable']	—	Chessground movable configuration pass-through
animation	Config['animation']	—	Chessground animation configuration pass-through
className	string	—	CSS class for the root container
style	CSSProperties	—	Inline styles for the root container
boardClassName	string	—	CSS class for the board wrapper
boardStyle	CSSProperties	—	Inline styles for the board wrapper
moveHistoryClassName	string	—	CSS class for move history panel
navigationClassName	string	—	CSS class for navigation controls
children	ReactNode	—	Additional children rendered after the board layout

Compound API

For custom layouts, compose Board, MoveHistory, Navigation, and BoardControls independently inside a ChessProvider. Each component reads from shared context.

import {
  ChessProvider, Board,
  MoveHistory, Navigation, BoardControls,
} from "@mdwebb/react-chess";

<ChessProvider pgn={pgn} theme="blue">
  <div style={{ display: "flex", gap: "1rem" }}>
    <div>
      <Board width={400} height={400} />
      <Navigation />
      <BoardControls />
    </div>
    <MoveHistory />
  </div>
</ChessProvider>

ProviderChessProvider

Wraps compound components to provide shared chess game state and methods via React context. Use useChess() to access the context in custom components.

Prop	Type	Default	Description
children*	ReactNode	—	Child components that consume chess context
fen	string	"start"	FEN string for initial position
pgn	string	—	PGN string to load a game
orientation	PieceColor	"white"	Initial board orientation
theme	ChessboardTheme	"brown"	Theme preset or custom theme object
autoPromoteToQueen	boolean	false	Skip promotion dialog, always promote to queen
enableKeyboardNavigation	boolean	true	Enable keyboard navigation for child components

ComponentBoard

Renders the interactive chess board via Chessground. Must be inside a ChessProvider.

Prop	Type	Default	Description
width	string \| number	"400px"	Board width
height	string \| number	"400px"	Board height
showCoordinates	boolean	true	Show coordinate labels
draggable	Config['draggable']	—	Chessground draggable config
movable	Config['movable']	—	Chessground movable config
premovable	Config['premovable']	—	Chessground premove config
drawable	Config['drawable']	—	Chessground drawing config
highlight	Config['highlight']	—	Chessground highlight config
animation	Config['animation']	—	Chessground animation config
className	string	—	CSS class for the board wrapper
style	CSSProperties	—	Inline styles for the board wrapper

ComponentMoveHistory

Scrollable move list with PGN metadata, annotations, and clickable moves for navigation. All props are optional when used inside ChessProvider.

Prop	Type	Default	Description
moves	Move[]	—	Move array (uses context if omitted)
onMoveClick	(index: number) => void	—	Called when a move is clicked
currentMoveIndex	number	—	Index of the active move (-1 = start)
annotations	Record<number, string>	—	Move annotations (e.g. "!!", "?!")
comments	Record<number, string>	—	Move comments from PGN
variations	Record<number, string[]>	—	Variation lines
clockTimes	Record<number, string>	—	Clock times per move
evaluations	Record<number, string>	—	Position evaluations per move
ravs	Record<number, RAV[]>	—	Recursive annotation variations
headers	PGNHeaders	—	PGN header metadata (Event, Players, etc.)
width	string \| number	—	Panel width
className	string	—	CSS class
style	CSSProperties	—	Inline styles

ComponentNavigation

First / Previous / Next / Last buttons for stepping through moves. Handlers default to context methods when omitted.

Prop	Type	Default	Description
onFirst	() => void	—	Called when First button clicked (uses context if omitted)
onPrevious	() => void	—	Called when Previous button clicked
onNext	() => void	—	Called when Next button clicked
onLast	() => void	—	Called when Last button clicked
canGoForward	boolean	—	Enable/disable next and last buttons
canGoBackward	boolean	—	Enable/disable first and previous buttons
className	string	—	CSS class

ComponentBoardControls

Board control buttons (flip, etc.). Handlers default to context methods when omitted.

Prop	Type	Default	Description
onFlip	() => void	—	Called when flip button clicked (uses context if omitted)
showFlipButton	boolean	true	Show the flip board button
className	string	—	CSS class

HookuseChess()

Access the full chess context inside any component within a ChessProvider. Returns game state, navigation methods, and configuration.

import { useChess } from "@mdwebb/react-chess";

function MyComponent() {
  const {
    game,              // chess.js instance
    fen,               // current FEN
    orientation,       // "white" | "black"
    moveHistory,       // Move[]
    currentMoveIndex,  // number (-1 = start)
    isCheck,           // boolean
    isGameOver,        // boolean
    flipBoard,         // () => void
    makeMove,          // (from, to, promotion?) => boolean
    navigateToMove,    // (index) => void
    goFirst,           // () => void
    goPrevious,        // () => void
    goNext,            // () => void
    goLast,            // () => void
  } = useChess();
}

Callbacks

Event handlers available on both Chessboard and ChessProvider. All callbacks are optional and receive fully typed arguments.

Prop	Type	Default	Description
onMove	(from: Key, to: Key, move: Move) => void	—	Fires after every legal move. Receives origin/destination squares and the chess.js Move object.
onCheck	(color: PieceColor) => void	—	Fires when a side is placed in check. Receives the color in check.
onGameOver	(result: GameOverResult) => void	—	Fires on checkmate, stalemate, or draw. Result includes winner and reason.
onPromotion	(from: Key, to: Key, piece: PromotionPiece) => void	—	Fires after pawn promotion. Receives the chosen piece type.
onIllegalMove	(from: string, to: string) => void	—	Fires when a player attempts an illegal move.
onFlip	(orientation: PieceColor) => void	—	Fires when the board orientation changes.
onPositionChange	(fen: string, moves: Move[]) => void	—	Fires after any position update. Receives current FEN and full move history.

<Chessboard
  onMove={(from, to, move) => {
    console.log(`${move.san} (${from} → ${to})`);
  }}
  onCheck={(color) => {
    console.log(`${color} is in check!`);
  }}
  onGameOver={(result) => {
    if (result.winner) {
      alert(`${result.winner} wins by ${result.reason}`);
    } else {
      alert(`Draw: ${result.reason}`);
    }
  }}
  onPromotion={(from, to, piece) => {
    console.log(`Promoted to ${piece}`);
  }}
/>

Ref API

Access imperative methods and underlying chess.js / chessground instances via a React ref.

Try imperative methods

const boardRef = useRef<ChessboardRef>(null);

<Chessboard ref={boardRef} pgn="..." />

// Imperative methods:
boardRef.current?.flip();
boardRef.current?.goNext();
boardRef.current?.goFirst();
boardRef.current?.navigateToMove(5);

// Access underlying instances:
boardRef.current?.game;  // chess.js
boardRef.current?.api;   // chessground

Prop	Type	Default	Description
api	Api \| null	—	Raw Chessground API instance for advanced control
game	Chess \| null	—	chess.js game instance for direct game state access
flip()	() => void	—	Flip the board orientation
navigateToMove(i)	(index: number) => void	—	Jump to a specific move by index
goFirst()	() => void	—	Navigate to the starting position
goPrevious()	() => void	—	Navigate to the previous move
goNext()	() => void	—	Navigate to the next move
goLast()	() => void	—	Navigate to the last move

Themes

Pass a preset name ("brown", "blue", "green", "gray") or a custom theme object. Use themePresets to access preset colors programmatically.

brown

blue

green

gray

// Use a preset
<Chessboard theme="blue" />

// Use a custom theme object
<Chessboard theme={{
  lightSquare: "#f0d9b5",
  darkSquare: "#b58863",
  selectedSquare: "rgba(20, 85, 30, 0.5)",
  lastMoveHighlight: "rgba(155, 199, 0, 0.41)",
  moveDestination: "rgba(20, 85, 30, 0.5)",
  checkHighlight: "rgba(255, 0, 0, 0.6)",
}} />

// Access preset values
import { themePresets } from "@mdwebb/react-chess";
console.log(themePresets.brown.darkSquare); // "#b58863"

Prop	Type	Default	Description
lightSquare*	string	—	CSS color for light squares
darkSquare*	string	—	CSS color for dark squares
selectedSquare	string	—	Highlight color for the selected piece square
lastMoveHighlight	string	—	Highlight color for the last move squares
moveDestination	string	—	Indicator color for legal move destinations
checkHighlight	string	—	Highlight color when king is in check

Types Reference

All exported TypeScript types for full type safety.

type PieceColor = "white" | "black";
type PromotionPiece = "q" | "r" | "b" | "n";
type ChessboardLayout = "horizontal" | "vertical" | "board-only";
type ChessboardThemePreset = "brown" | "blue" | "green" | "gray";
type ChessboardTheme = ChessboardThemePreset | CustomTheme;

interface CustomTheme {
  lightSquare: string;
  darkSquare: string;
  selectedSquare?: string;
  lastMoveHighlight?: string;
  moveDestination?: string;
  checkHighlight?: string;
}

interface GameOverResult {
  winner?: PieceColor;
  reason:
    | "checkmate"
    | "stalemate"
    | "insufficient_material"
    | "threefold_repetition"
    | "fifty_move_rule"
    | "draw";
}

interface PGNHeaders {
  White?: string;
  Black?: string;
  Date?: string;
  Event?: string;
  Site?: string;
  Result?: string;
  Round?: string;
  WhiteElo?: string;
  BlackElo?: string;
  ECO?: string;
  [key: string]: string | undefined;
}

interface PGNMetadata {
  annotations: Record<number, string>;
  comments: Record<number, string>;
  variations: Record<number, string[]>;
  clockTimes: Record<number, string>;
  evaluations: Record<number, string>;
  ravs: Record<number, { moves: string; comment?: string }[]>;
  headers: PGNHeaders;
}

interface ChessboardRef {
  api: Api | null;       // Chessground API
  game: Chess | null;    // chess.js instance
  flip: () => void;
  navigateToMove: (index: number) => void;
  goFirst: () => void;
  goPrevious: () => void;
  goNext: () => void;
  goLast: () => void;
}

// Components
import {
  Chessboard,
  ChessProvider,
  Board,
  MoveHistory,
  Navigation,
  BoardControls,
} from "@mdwebb/react-chess";

// Hook
import { useChess } from "@mdwebb/react-chess";

// Theme utilities
import {
  themePresets,
  resolveTheme,
  themeToCSSSVars,
  generateBoardSVG,
} from "@mdwebb/react-chess";

// Types
import type {
  ChessboardProps,
  ChessboardRef,
  ChessProviderProps,
  BoardProps,
  MoveHistoryProps,
  NavigationProps,
  BoardControlsProps,
  ChessboardTheme,
  ChessboardThemePreset,
  CustomTheme,
  ChessboardLayout,
  PieceColor,
  PromotionPiece,
  GameOverResult,
  PGNMetadata,
  PGNHeaders,
  ChessContextValue,
} from "@mdwebb/react-chess";