@ammar-ahmed22/react-chess

Custom built Chess UI components/hooks for React to be used with my custom built Chess engine.

What is this?

I don't intend for many people to see this, however, if you do stumble across this, this library was created merely as a learning exercise for myself. There is already a more robust/complete Chess UI built for React called react-chessboard.

I built this with two distinct learning goals:

1. To learn how to create React component libraries
2. To hone my React skills by building a complex UI such as a Chess board

I mentioned in the description that it is meant to be used with my Chess engine, which is true; however, I tried to make the components/hooks as flexible as possible so that it could potentially be used by any Chess engines or to simply view Chess positions, etc.

Installation

npm install --save @ammar-ahmed22/react-chess

Features

• Responsive Board Size: Squares and board height auto-update with one prop
• FEN Position: Set the position of the board with a FEN string
• Board Orientation: Flip the orientation of the board
• Custom Actions: Various custom actions for each individual square are available with single callbacks (e.g onSquareClick)

• UI Customization: Change light/dark square colors, override move identifiers, etc.
• Valid Move Identifiers: Handles showing valid moves onClick when provided
• Board Coordinate Identifiers: Show coordinate identifiers

Usage

Render a Chess FEN position

import { ChessBoard } from "@ammar-ahmed22/react-chess";
import { Chess } from "@ammar-ahmed22/chess-engine";

export default function App() {
  const chess = new Chess();
  return (
    <div>
      <ChessBoard 
        position={chess.fen()} // starts off with the starting position
      />
    </div>
  )
}

ChessBoard Props

Prop	Type	Default	Description
darkColor	string	"#b58863"	The color to use for dark squares. Must be a valid CSS color string (e.g. "#fff", "rgb(255, 255, 255)", etc.)
disabled	boolean	false	If true, disables the board and darkens it
flipBoard	boolean	false	If true, board is flipped.
lightColor	string	"#f0d9b5"	The color to use for light squares. Must be a valid CSS color string (e.g. "#fff", "rgb(255, 255, 255)", etc.)
pieceSet	PieceSet | PieceImageMap	"cases"	The piece set (images) to use, provided are the cases and neo piece sets. Otherwise, provide a custom piece image map to use custom pieces.
showCoordinates	boolean	false	If true, coordinates identifiers will be shown. Rank numbers will be shown on the left most file, file letters will be shown on the bottom most rank (irrespective of board orientation).
size	string | number	"90vh"	The size of the board as a CSS string value or a number in pixels. Square sizes will be calculated accordingly
squareDraggable	boolean | (square: SquareType) => boolean	true	If false, cannot be dragged. If a function is passed, the result of the function will determine if that square can be dragged. @param square - If a function is passed, the square that will be dragged
moveIdentifier	React.ReactNode	N/A	If provided, overrides the default move identifier
onSquareClick	(square: SquareType) => void	N/A	Callback function when a square is clicked @param square - The square that is being clicked
onSquareDrag	(square: SquareType, ev: React.DragEvent<HTMLImageElement>) => void	N/A	Callback function that is called while a piece is being dragged. @param square - The square that is being dragged @param ev - The drag event for the piece image being dragged.
onSquareDragEnd	(square: SquareType, ev: React.DragEvent<HTMLImageElement>) => void	N/A	Callback function that is called when a piece stops being dragged @param square - The square that was being dragged @param ev - The drag event for the piece image that was being dragged.
onSquareDragEnter	(square: SquareType, ev: React.DragEvent<HTMLDivElement>) => void	N/A	Callback function that is called when a dragged piece enters a square @param square - The square that is being entered @param ev - The drag event for the square that is being entered.
onSquareDragLeave	(square: SquareType, ev: React.DragEvent<HTMLDivElement>) => void	N/A	Callback function that is called when a dragged piece leaves a square @param square - The square that is being left. @param ev - The drag event for the square that is being left.
onSquareDragOver	(square: SquareType, ev: React.DragEvent<HTMLDivElement>) => void	N/A	Callback function that is called when a piece is dragged over a square. @param square - The square that the piece is being dragged over. @param ev - The drag event for the square that is being dragged over.
onSquareDragStart	(square: SquareType, ev: React.DragEvent<HTMLImageElement>) => void	N/A	Callback function that is called when a piece is starting to be dragged @param square - The square that is being dragged. @param ev - The drag event for the piece image that is being dragged.
onSquareDrop	(from: SquareType, on: SquareType, ev: React.DragEvent<HTMLDivElement>) => void	N/A	Callback function that is called when a piece is dropped over a square @param from - The square that the piece is being dragged from @param on - The square that the piece is being dropped on @param ev - The drag event for the square that is being dropped on.
position	string	N/A	The Chess position to render as a FEN (without metadata) string.
setPromotedPiece	React.Dispatch<React.SetStateAction<PromotePieceType | undefined>>	N/A	React Set State function to set the selected promote piece when modal is shown
showPromotionModal	PromotionData	N/A	If provided, shows the piece promotion modal at the provided square.
validMoves	HalfMove[]	N/A	If provided, when clicking on a piece, shows valid moves

License

MIT