react-chessboard

The project uses semantic-release to automatically determine version numbers, generate release notes, and publish to npm based on your commit types:

• Major version bump (e.g., 1.1.2 -> 2.0.0): Triggered by commits containing ! in the type (e.g., feat! or fix!).
• Minor version bump (e.g., 1.0.0 -> 1.1.0): Triggered by feat commits.
• Patch version bump (e.g., 1.0.0 -> 1.0.1): Triggered by fix commits.

For multiplayer experiences, maintain two distinct game states:

• Local Game State: The state the current player sees on their own board.
• Remote Game State: The state the player sees on their opponent's board.

Synchronization Pattern: When a player makes a move, update the local game state immediately for responsiveness, then send that state over the network to the opponent. The opponent's client receives the update and applies it to their remote game state, resulting in a slight delay equal to the network latency.

The component can be used to create non-standard chess variants:

• Mini Puzzles: Create smaller or constrained boards with logic that follows predefined move sequences.
• Four Player Chess: Implement boards with multiple orientations and different piece colors to support variants like the Chess.com 4-player version.

The Chessboard component (and ChessboardProvider when using features like spare pieces) can be customized using an options prop. This prop accepts an object containing various configuration settings for behavior, styling, and event handling.

To use it, pass an object to the options prop of your component:

<Chessboard options={{ /* your configuration here */ }} />

React Chessboard is designed as a pure UI component.

• Responsibility: It handles the visual representation of the board, piece rendering, animations, drag-and-drop interactions, and user input events.
• Separation of Concerns: It does not contain any chess game logic (e.g., it doesn't know if a move is legal or if a player is in check).
• Integration: You must integrate an external chess logic library (such as chess.js) to manage the game state, validate moves, and provide the board state to the component via the options prop.

Spare pieces allow you to drag pieces onto or off the board, which is useful for puzzles or custom setups.

Requirements:

1. You must wrap both the chessboard and the spare pieces in a ChessboardProvider.
2. Prop Migration: All props that are normally passed directly to the Chessboard component must now be passed to the ChessboardProvider via its options prop.

Handling piece removal: When dragging a piece off the board, the onPieceDrop handler will be triggered with targetSquare set to null. You can use this to implement logic for removing pieces from the game state.

// Conceptual implementation pattern
<ChessboardProvider options={{ position: 'start', onPieceDrop: handleDrop }}>
  <Chessboard />
  <SparePieces />
</ChessboardProvider>

Version 5 is a ground-up rewrite that is significantly smaller (27% smaller minified, 19% smaller gzipped) and has fewer dependencies. However, it introduces several breaking changes regarding environment requirements and API structures. You must ensure your environment meets the new minimum requirements for React and Node.js before proceeding with the upgrade.

# Example upgrade command (see specific package manager below)
npm install react@^19.0.0 react-dom@^19.0.0

To allow users to select which piece a pawn promotes to, use the onPieceDrop prop to intercept the promotion move.

Workflow:

1. Capture the promotion move via the onPieceDrop callback.
2. Trigger a UI element (like a dialog or modal) to let the user select the desired piece.
3. Once the selection is made, update the board's position prop with the new state to reflect the promotion move on the board.

To provide a flexible user experience that supports both dragging pieces and clicking squares to move, implement both the onPieceDrop and onSquareClick props in tandem.

// Conceptual implementation pattern
<Chessboard 
  onPieceDrop={(source, target) => { /* drag logic */ return true; }}
  onSquareClick={(square) => { /* click logic */ }}
/>