@ammar-ahmed22/react-chess
TypeScript icon, indicating that this package has built-in type declarations

0.2.1 • Public • Published

@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

Readme

Keywords

none

Package Sidebar

Install

npm i @ammar-ahmed22/react-chess

Weekly Downloads

1

Version

0.2.1

License

MIT

Unpacked Size

1.23 MB

Total Files

38

Last publish

Collaborators

  • amm6rr