Table of Contents

- Overview
- Features
- Installation
- Quick Start
- Demo
- API Reference
- ChessGame.Root
- ChessGame.Board
- ChessGame.Sounds
- ChessGame.KeyboardControls
- ChessGame.Clock
- Hooks
- useChessGameContext
- Examples
- License

Overview

@react-chess-tools/react-chess-game is a React component that bridges chess.js with react-chessboard to offer a full-featured, ready-to-integrate chess board experience.

Built using a compound component pattern (similar to Radix UI), it provides a ChessGameContext that you can use to customize and enhance the game while maintaining sensible defaults.

The package now includes integrated chess clock functionality powered by @react-chess-tools/react-chess-clock.

Features

- Move-by-click - Click to select and move pieces
- Sound effects - Built-in sounds for moves, captures, check, and game over
- Square highlighting - Visual feedback for valid moves and last move
- Keyboard controls - Navigate through game history with arrow keys
- Integrated Chess Clock - Built-in clock support with multiple timing methods
- Full game state - Access to check, checkmate, stalemate, draw detection
- TypeScript - Full TypeScript support with comprehensive type definitions
- Customizable - Override any default with your own implementation

Installation

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

`bash
yarn add @react-chess-tools/react-chess-game
`

`bash
pnpm add @react-chess-tools/react-chess-game
`

Quick Start

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

function App() {
return (





);
}
`

With a chess clock:

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

function App() {
return (






);
}
`

Demo

Visit the live demo to see the component in action.

API Reference

$3

The root component that provides ChessGameContext to all child components. It instantiates a Chess instance using the fen prop and optionally sets up a chess clock.

Note: This is a logic-only component (Context Provider). It does not render any DOM elements.

#### Props

| Name | Type | Default | Description |
| ------------------ | ----------------------- | ----------------- | -------------------------------------------------------- |
| children | ReactNode | - | Child components |
| fen | string | Starting position | Initial FEN string for the chess game |
| orientation | "w" \| "b" | "w" | Board orientation (white or black at bottom) |
| theme | PartialChessGameTheme | - | Optional theme configuration |
| timeControl | TimeControlConfig | - | Optional clock configuration to enable chess clock |
| autoSwitchOnMove | boolean | true | Auto-switch clock on move (when timeControl is provided) |

#### Example

`tsx
fen="rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1"
orientation="b"
timeControl={{ time: "10+5" }}
>


`

$3

The main chess board component. Renders the board and pieces using react-chessboard v5.

Supports ref forwarding and all standard HTML div attributes (className, style, id, data-_, aria-_, etc.).

#### Props

| Name | Type | Description |
| ----------- | -------------------------------- | ------------------------------------------------------------------------- |
| options | ChessboardOptions | Options forwarded to react-chessboard. Your values merge with defaults. |
| ref | Ref | Forwarded ref to the wrapper div element |
| className | string | Custom CSS class names |
| style | CSSProperties | Custom inline styles |
| ... | HTMLAttributes | All standard HTML div attributes |

#### Example

`tsx

options={{
squareStyles: { e4: { boxShadow: "inset 0 0 0 2px #4f46e5" } },
onPieceDrop: ({ sourceSquare, targetSquare }) => {
console.log(Move: ${sourceSquare} -> ${targetSquare});
return true;
},
showNotation: true,
animationDurationInMs: 300,
}}
className="my-custom-board"
style={{ borderRadius: "8px" }}
id="game-board"
data-testid="chess-board"
/>

`

$3

Provides sound effects for the chess game. Uses built-in sounds by default, but custom sounds can be provided as base64-encoded strings.

Note: This is a logic-only component that returns null. It sets up audio functionality via hooks.

#### Props

| Name | Type | Default | Description |
| -------- | -------------------------------- | ------- | ------------------------------------------------------------------------- |
| sounds | Partial> | - | Custom sounds configuration. Keys: move, capture, check, gameOver |

#### Example

`tsx

sounds={{
move: customMoveSound,
capture: customCaptureSound,
}}
/>


`

$3

Enables keyboard navigation through the game history.

Note: This is a logic-only component that returns null. It sets up keyboard event listeners via hooks.

#### Props

| Name | Type | Default | Description |
| ---------- | ------------------ | ------------------------- | --------------------------------------------- |
| controls | KeyboardControls | defaultKeyboardControls | Object mapping key names to handler functions |

Default Controls:

- ArrowLeft - Go to previous move
- ArrowRight - Go to next move
- ArrowUp - Go to starting position
- ArrowDown - Go to latest move

#### Example

`tsx

controls={{
ArrowLeft: (ctx) => ctx.methods.goToPreviousMove(),
ArrowRight: (ctx) => ctx.methods.goToNextMove(),
Home: (ctx) => ctx.methods.goToStart(),
End: (ctx) => ctx.methods.goToEnd(),
}}
/>


`

$3

Integrated chess clock components. When timeControl is provided to ChessGame.Root, these components become available to display and control the clock.

The clock automatically switches when moves are made on the board (can be disabled with autoSwitchOnMove={false}).

Note: These are wrapper components that use the clock state from ChessGame.Root. No need for a separate ChessClock.Root provider.

#### Available Components

| Component | Description |
| --------------------------- | -------------------------------------------- |
| ChessGame.Clock.Display | Displays the current time for a player |
| ChessGame.Clock.Switch | Button to manually switch the active clock |
| ChessGame.Clock.PlayPause | Button to start, pause, and resume the clock |
| ChessGame.Clock.Reset | Button to reset the clock |

#### ChessGame.Clock.Display

Displays the current time for a player.

`tsx
color="white"
format="auto"
style={{ fontFamily: "monospace", fontSize: "24px" }}
/>
`

Props:

| Name | Type | Default | Description |
| ------------ | ------------------------------------------- | -------- | ---------------------------------- |
| color | "white" \| "black" | - | Player color to display (required) |
| format | "auto" \| "mm:ss" \| "ss.d" \| "hh:mm:ss" | "auto" | Time format |
| formatTime | (milliseconds: number) => string | - | Custom time formatting function |
| ... | HTMLAttributes | - | All standard HTML div attributes |

#### ChessGame.Clock.Switch

A button that manually switches the active player's clock.

`tsx
Switch Turn
`

Props:

| Name | Type | Default | Description |
| --------- | ----------------------------------------- | ------- | -------------------------------------- |
| asChild | boolean | false | Render as child element (slot pattern) |
| ... | ButtonHTMLAttributes | - | All standard HTML button attributes |

#### ChessGame.Clock.PlayPause

A button to start, pause, and resume the clock.

`tsx
startContent="Start Game"
pauseContent="Pause"
resumeContent="Resume"
/>
`

Props:

| Name | Type | Default | Description |
| ----------------- | ----------------------------------------- | ------------- | -------------------------------------- |
| startContent | ReactNode | "Start" | Content shown when clock is idle |
| pauseContent | ReactNode | "Pause" | Content shown when clock is running |
| resumeContent | ReactNode | "Resume" | Content shown when clock is paused |
| delayedContent | ReactNode | "Start" | Content shown when clock is delayed |
| finishedContent | ReactNode | "Game Over" | Content shown when clock is finished |
| asChild | boolean | false | Render as child element (slot pattern) |
| ... | ButtonHTMLAttributes | - | All standard HTML button attributes |

#### ChessGame.Clock.Reset

A button that resets the clock.

`tsx
Reset;

{
/ Reset with new time control /
}

Change to 10+5
;
`

Props:

| Name | Type | Description |
| ------------- | ----------------------------------------- | --------------------------------------------- |
| timeControl | TimeControlInput | New time control to apply on reset (optional) |
| asChild | boolean | Render as child element (slot pattern) |
| ... | ButtonHTMLAttributes | All standard HTML button attributes |

For more details on time control formats, timing methods, and clock start modes, see the @react-chess-tools/react-chess-clock documentation.

Hooks

$3

Access the chess game context from any child component.

`tsx
import { useChessGameContext } from "@react-chess-tools/react-chess-game";

function GameStatus() {
const { currentFen, info, methods, clock } = useChessGameContext();

return (


| Name | Type | Description |
| ------------------ | ----------------------------- | ------------------------------------- |
| game | Chess | The underlying chess.js instance |
| orientation | "w" \| "b" | Current board orientation |
| currentFen | string | Current FEN string |
| currentPosition | string | Current position in game history |
| currentMoveIndex | number | Index of current move in history |
| isLatestMove | boolean | Whether viewing the latest position |
| methods | Methods | Methods to interact with the game |
| info | Info | Game state information |
| clock | UseChessClockReturn \| null | Clock state (if timeControl provided) |

#### Methods

| Method | Type | Description |
| ------------------ | ------------------------------------------------ | --------------------------------------- |
| makeMove | (move: string \| MoveObject) => boolean | Make a move, returns true if successful |
| setPosition | (fen: string, orientation: "w" \| "b") => void | Set a new position |
| flipBoard | () => void | Flip the board orientation |
| goToMove | (moveIndex: number) => void | Jump to specific move (-1 = start) |
| goToStart | () => void | Go to starting position |
| goToEnd | () => void | Go to latest move |
| goToPreviousMove | () => void | Go to previous move |
| goToNextMove | () => void | Go to next move |

#### Info Object

| Property | Type | Description |
| ------------------------ | ------------ | ------------------------------------- |
| turn | "w" \| "b" | Current turn |
| isPlayerTurn | boolean | Whether it's the player's turn |
| isOpponentTurn | boolean | Whether it's the opponent's turn |
| moveNumber | number | Current move number |
| lastMove | Move | Last move made |
| isCheck | boolean | Whether current player is in check |
| isCheckmate | boolean | Whether it's checkmate |
| isDraw | boolean | Whether the game is a draw |
| isDrawn | boolean | Alias for isDraw |
| isStalemate | boolean | Whether it's stalemate |
| isThreefoldRepetition | boolean | Whether threefold repetition occurred |
| isInsufficientMaterial | boolean | Whether there's insufficient material |
| isGameOver | boolean | Whether the game has ended |
| hasPlayerWon | boolean | Whether the player has won |
| hasPlayerLost | boolean | Whether the player has lost |

Examples

$3

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

function FullFeaturedGame() {
return (





);
}
`

$3

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

function GameWithClock() {
return (





Reset

);
}
`

$3

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

function CustomPosition() {
// Sicilian Defense starting position
const sicilianFen =
"rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR w KQkq c6 0 2";

return (



);
}
`

$3

`tsx
import {
ChessGame,
useChessGameContext,
} from "@react-chess-tools/react-chess-game";

function MoveHistory() {
const { game, currentMoveIndex, methods } = useChessGameContext();
const history = game.history();

return (


function GameWithHistory() {
return (





);
}
`

$3

`tsx
import {
ChessGame,
useChessGameContext,
} from "@react-chess-tools/react-chess-game";

function GameStatus() {
const { info } = useChessGameContext();

if (info.isCheckmate) {
return (


function GameWithStatus() {
return (





);
}
`

$3

You can also use ChessClock components directly alongside ChessGame:

`tsx
import { ChessGame, ChessClock } from "@react-chess-tools/react-chess-game";

function GameWithSeparateClock() {
return (


License

This project is MIT licensed.

Show Your Support

Give a star if this project helped you!