ChessCanvas ♟️

A simple, scriptable chess-board rendering engine for React and Remotion. Create chess animations with custom moves, annotations, sound effects, and checkmate animations.

Installation

npm install @vshukla7/chesscanvas

Note: For sound effects to work, place chess sound .mp3 files (move, capture, check, castle, promote, checkmate) in your public /sounds folder (e.g., /public/sounds/move.mp3).

Configuration Reference

Customize visual styles by passing configuration settings to chesscanvas(config).

Available Board Themes (boardTheme)

| Theme Name | Style Description | Light Square | Dark Square | | :--- | :--- | :--- | :--- | | "classic" | Cream & Forest Green (Lichess default look) | #ffffdd | #86a666 | | "walnut" | Warm Wood Tones | #f0d9b5 | #b58863 | | "tournament" | High-Contrast Gray & White Broadcast style | #ececec | #a9a9a9 | | "blue" | Chess.com Blue/Gray style | #dee3e6 | #8ca2ad |

Available Piece Sets (pieceSet)

| Set Name | Visual Description | | :--- | :--- | | "cburnett" | Lichess Default (modern vector sprites) | | "merida" | Classic Outline (traditional print/book layout) |

Piece ID Reference

Every piece on the board has a unique ID used in the script (e.g. WP5, WK, BQ).

• White Pieces Prefix: W (e.g., WP1 to WP8 for pawns, WK for King, WQ for Queen, WN1/WN2 for Knights)
• Black Pieces Prefix: B (e.g., BP1 to BP8 for pawns, BK for King, BQ for Queen, BN1/BN2 for Knights)

Starting Positions & Piece IDs:

Simple Example

import { useMemo } from "react";
import { Player } from "@remotion/player";
import { chesscanvas } from "@vshukla7/chesscanvas";

export default function ChessPlayer() {
  const canvas = useMemo(() => {
    const { script, Component, timeline } = chesscanvas({
      boardTheme: "classic",
      pieceSet: "cburnett",
    });

    // Write your script
    script
      .move("WP5", "e4")
      .move("BP5", "e5")
      .move("WQ", "h5")
      .highlight("yellow", "f7")
      .arrow("red", "h5", "f7")
      .move("WQ", "f7") // Checkmate!
      .wait(2.0);

    timeline.finalize();
    const duration = timeline.suggestedDurationInFrames(30, "fast");

    return { Component, duration };
  }, []);

  return (
    <Player
      component={canvas.Component}
      durationInFrames={canvas.duration}
      fps={30}
      compositionWidth={800}
      compositionHeight={800}
      numberOfSharedAudioTags={100}
      controls
    />
  );
}

Script API

• .move(pieceId, square, options): Slides a piece from its current square to a target square.
  • pieceId (string): ID of the piece to move (e.g. "WP5", "WK", "BP1"). See Piece ID Reference for values.
  • square (string): Algebraic target coordinate (range: "a1" to "h8").
  • options (object, optional):
    • duration (number): Slide transition time in timeline ticks (default: 1.0, range: > 0).
    • promotion (string): Target promotion type (value: "Q" | "R" | "B" | "N", only valid for pawns moving to their final rank).
• .arrow(color, from, to, options): Draws a vector arrow on the board.
  • color (string): Predefined drawing color (value: "red" | "blue" | "green" | "yellow" | "orange").
  • from (string): Origin square coordinate (range: "a1" to "h8").
  • to (string): Destination square coordinate (range: "a1" to "h8").
  • options (object, optional):
    • duration (number): Draw fade-in time in timeline ticks (default: 0.25, range: > 0).
    • persist (boolean): Whether the arrow remains on the board after the step finishes (default: true).
• .highlight(color, square, options): Highlights a board square.
  • color (string): Predefined highlight color (value: "yellow" | "red" | "blue" | "green" | "orange").
  • square (string): Target coordinate (range: "a1" to "h8").
  • options (object, optional):
    • duration (number): Fade-in time in timeline ticks (default: 0.25, range: > 0).
    • persist (boolean): Whether the highlight remains active (default: true).
• .clearArrows(): Clears all active arrows from the board. Takes no parameters.
• .clearHighlights(): Clears all active cell highlights from the board. Takes no parameters.
• .wait(units): Inserts a timed pause before starting the next move.
  • units (number): Pause duration in ticks (range: > 0).
  • Timing in Seconds (at 30 fps):
    • In "fast" speed mode (24 frames/tick), wait(1.0) pauses for 0.8 seconds.
    • In "normal" speed mode (45 frames/tick), wait(1.0) pauses for 1.5 seconds.
    • Formula: seconds = units * (framesPerTick / fps).
• .sound(enabled): Programmatically enables or disables sound effects for subsequent moves.
  • enabled (boolean): Value true (default) to enable sound effects, false to mute them.
• .speed(val): Configures move transition pacing.
  • val (string): Pacing mode (value: "normal" for 45 frames per tick, "fast" for 24 frames per tick).
• .showResultBanner(enabled): Toggles display of the checkmate victory banner.
  • enabled (boolean): Value true (default) to show banner, false to hide it.
• .showCheckmateAnimation(enabled): Toggles checkmate graphic animations (sinking king, red flag, gold crown).
  • enabled (boolean): Value true (default) to play animations, false to bypass them.