chessiro-canvas

Lightweight React chessboard with low overhead interaction primitives inspired by chessground.

Built for https://chessiro.com, but can be used by all

• Zero runtime dependencies
• TypeScript-first API
• Drag, click-move, arrows, marks, premoves, promotion, overlays
• Built for controlled usage in analysis and coaching apps

Install

npm install chessiro-canvas

Quick Start

Your container must define width, and board height follows width (square board).

import { ChessiroCanvas, INITIAL_FEN } from 'chessiro-canvas';

export default function App() {
  return (
    <div style={{ width: 520 }}>
      <ChessiroCanvas position={INITIAL_FEN} />
    </div>
  );
}

ChessiroCanvas is a controlled component. For playable boards, your onMove must update position after validating the move (typically via chess.js or chessops).

Piece Rendering (Default + Custom)

ChessiroCanvas ships with embedded default SVG pieces and renders them by default with no asset hosting setup.

<ChessiroCanvas position={fen} />

Piece license note:

• Bundled default piece artwork is generated from react-chessboard defaults (MIT license).
• You can replace it any time via pieceSet.path.

Use pieceSet.path only when you want to override with your own hosted piece set.

<ChessiroCanvas
  position={fen}
  pieceSet={{
    id: 'alpha',
    name: 'Alpha',
    path: '/pieces/alpha', // expects /pieces/alpha/wp.svg ... /bk.svg
  }}
/>

If pieces appear as broken images, upgrade to the latest package version.

Customize Legal Move UI

Use squareVisuals to customize legal dots, capture rings, premove hints, marks, and check overlay.

<ChessiroCanvas
  position={fen}
  dests={dests}
  squareVisuals={{
    legalDot: 'rgba(30, 144, 255, 0.55)',
    legalDotOutline: 'rgba(255, 255, 255, 0.95)',
    legalCaptureRing: 'rgba(30, 144, 255, 0.8)',
    premoveDot: 'rgba(155, 89, 182, 0.55)',
    premoveCaptureRing: 'rgba(155, 89, 182, 0.75)',
    selectedOutline: 'rgba(255, 255, 255, 1)',
    markOverlay: 'rgba(244, 67, 54, 0.6)',
    markOutline: 'rgba(244, 67, 54, 0.9)',
  }}
/>

Customize Other UI Layers

<ChessiroCanvas
  position={fen}
  showMargin={true}
  marginRadius={16}
  boardRadius={14}
  arrowVisuals={{
    lineWidth: 0.2,
    opacity: 1,
    markerWidth: 5,
    markerHeight: 5,
  }}
  notationVisuals={{
    fontFamily: 'JetBrains Mono, monospace',
    fontSize: 11,
    onBoardFontSize: 11,
    opacity: 0.95,
  }}
  promotionVisuals={{
    panelColor: 'rgba(20, 24, 36, 0.98)',
    titleColor: '#f2f6ff',
    optionBackground: 'rgba(255, 255, 255, 0.08)',
    optionTextColor: '#f2f6ff',
    cancelTextColor: '#cbd5e1',
  }}
  overlayVisuals={{
    background: 'rgba(2, 6, 23, 0.85)',
    color: '#f8fafc',
    borderRadius: '6px',
    fontSize: '11px',
  }}
/>

boardRadius controls inner board corners, and marginRadius controls outer margin corners. Both work independently, so you can style rounded inner + outer frames together. For notation sizing, notationVisuals.fontSize and notationVisuals.onBoardFontSize accept either number or CSS string.

Integration With chess.js

npm install chess.js chessiro-canvas

import { useMemo, useState } from 'react';
import { Chess } from 'chess.js';
import { ChessiroCanvas, type Dests, type Square } from 'chessiro-canvas';

export function ChessJsBoard() {
  const [chess] = useState(() => new Chess());
  const [fen, setFen] = useState(() => chess.fen());

  const dests = useMemo<Dests>(() => {
    const map = new Map<Square, Square[]>();
    const moves = chess.moves({ verbose: true });
    for (const move of moves) {
      const from = move.from as Square;
      const to = move.to as Square;
      const current = map.get(from);
      if (current) current.push(to);
      else map.set(from, [to]);
    }
    return map;
  }, [fen]);

  return (
    <ChessiroCanvas
      position={fen}
      turnColor={chess.turn()}
      movableColor={chess.turn()}
      dests={dests}
      onMove={(from, to, promotion) => {
        const result = chess.move({ from, to, promotion });
        if (!result) return false;
        setFen(chess.fen());
        return true;
      }}
    />
  );
}

Important for chess.js users:

• chess.js mutates the same Chess instance in place.
• Do not key useMemo/useEffect off the chess object reference for legal moves, check square, turn state, etc.
• Key derived UI state from fen (or move history), because fen changes on every accepted move.

Correct dependency pattern:

const [chess] = useState(() => new Chess());
const [fen, setFen] = useState(() => chess.fen());

const dests = useMemo(() => {
  const map = new Map();
  for (const move of chess.moves({ verbose: true })) {
    const list = map.get(move.from) ?? [];
    list.push(move.to);
    map.set(move.from, list);
  }
  return map;
}, [fen]); // <- use fen, not [chess]

Integration With chessops

npm install chessops chessiro-canvas

import { useMemo, useState } from 'react';
import { Chess } from 'chessops/chess';
import { chessgroundDests } from 'chessops/compat';
import { parseFen, makeFen } from 'chessops/fen';
import { parseUci } from 'chessops/util';
import { ChessiroCanvas, INITIAL_GAME_FEN } from 'chessiro-canvas';

export function ChessopsBoard() {
  const [pos, setPos] = useState(() =>
    Chess.fromSetup(parseFen(INITIAL_GAME_FEN).unwrap()).unwrap(),
  );

  const fen = useMemo(() => makeFen(pos.toSetup()), [pos]);
  const dests = useMemo(() => chessgroundDests(pos), [pos]);
  const turn = pos.turn === 'white' ? 'w' : 'b';

  return (
    <ChessiroCanvas
      position={fen}
      turnColor={turn}
      movableColor={turn}
      dests={dests}
      onMove={(from, to, promotion) => {
        const uci = `${from}${to}${promotion ?? ''}`;
        const move = parseUci(uci);
        if (!move || !pos.isLegal(move)) return false;
        const next = pos.clone();
        next.play(move);
        setPos(next);
        return true;
      }}
    />
  );
}

INITIAL_FEN is piece-placement only (UI-friendly). For engine integrations, use INITIAL_GAME_FEN so castling rights are present.

Features

• FEN-based board rendering
• Built-in default piece set shipped with the package
• Click-to-move and drag-to-move
• Legal move dots and capture rings
• Premoves with optional external event hooks
• Right-click arrows and marks
• Last-move, check, and custom square highlights
• Move-quality badge support
• Promotion chooser
• Text overlays with custom renderer
• Keyboard callbacks (ArrowLeft, ArrowRight, Home, End, F, X, Escape)
• Theme, piece set, and custom piece renderer support

Core API

ChessiroCanvas props

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | position | string | start position | FEN (piece placement or full FEN; placement is parsed) | | orientation | 'white' \| 'black' | 'white' | Board orientation | | interactive | boolean | true | Disables move interactions when false | | turnColor | 'w' \| 'b' | undefined | Needed for turn-aware move/premove flow | | movableColor | 'w' \| 'b' \| 'both' | undefined | Restricts which side can move | | onMove | (from, to, promotion?) => boolean | undefined | Return true to accept move | | dests | Map<Square, Square[]> | undefined | Legal destinations per square | | lastMove | { from: string; to: string } \| null | undefined | Last move highlight | | check | string \| null | undefined | King-in-check square | | premovable | PremoveConfig | undefined | Enables premove and callbacks | | arrows | Arrow[] | [] | Controlled arrows | | onArrowsChange | (arrows) => void | undefined | Arrow updates | | markedSquares | string[] | internal | Controlled marks | | onMarkedSquaresChange | (squares) => void | undefined | Mark updates | | arrowBrushes | Partial<ArrowBrushes> | default set | Override arrow colors | | arrowVisuals | Partial<ArrowVisuals> | undefined | Customize arrow width, opacity, marker size, and arrow margin | | snapArrowsToValidMoves | boolean | true | Queen/knight snap behavior | | theme | BoardTheme | built-in theme | Board colors | | pieceSet | PieceSet | bundled default pieces | Optional custom piece asset path config | | pieces | Record<string, () => ReactNode> | undefined | Custom piece renderer map | | showMargin | boolean | true | Margin frame for notation | | marginThickness | number | 24 | Margin px | | marginRadius | number \| string | 4 | Outer margin frame corner radius | | boardRadius | number \| string | 0 | Board corner radius (works with or without margin) | | showNotation | boolean | true | Coordinate labels | | notationVisuals | Partial<NotationVisuals> | undefined | Customize notation font family, size, weight, color, and offsets | | highlightedSquares | Record<string, string> | {} | Arbitrary square background colors | | squareVisuals | Partial<SquareVisuals> | undefined | Customize legal/premove indicators, marks, selected outline, and check overlay | | moveQualityBadge | MoveQualityBadge \| null | undefined | Badge icon on square | | allowDragging | boolean | true | Drag interaction toggle | | allowDrawingArrows | boolean | true | Right-click arrows/marks toggle | | showAnimations | boolean | true | Piece animation toggle | | animationDurationMs | number | 200 | Piece animation length | | blockTouchScroll | boolean | false | Prevent scrolling on touch interaction | | overlays | TextOverlay[] | [] | Text overlays | | overlayRenderer | (overlay) => ReactNode | undefined | Custom overlay renderer | | overlayVisuals | Partial<OverlayVisuals> | undefined | Customize default overlay bubble style (when overlayRenderer is not provided) | | onSquareClick | (square) => void | undefined | Square click callback | | onClearOverlays | () => void | undefined | Called when board clears current ply overlays | | promotionVisuals | Partial<PromotionVisuals> | undefined | Customize promotion dialog backdrop, panel, option buttons, and text colors | | onPrevious onNext onFirst onLast onFlipBoard onShowThreat onDeselect | callbacks | undefined | Keyboard callback hooks | | className | string | undefined | Wrapper class | | style | CSSProperties | undefined | Wrapper style |

Exported helpers

• INITIAL_FEN
• INITIAL_GAME_FEN
• readFen(fen) / writeFen(pieces)
• premoveDests(square, pieces, color)
• preloadPieceSet(path)
• DEFAULT_ARROW_BRUSHES

Examples

Controlled legal moves (dests)

import { useMemo } from 'react';
import { ChessiroCanvas, type Dests, type Square } from 'chessiro-canvas';

function Board({ fen, legalMovesByFrom, onMove }) {
  const dests = useMemo<Dests>(() => {
    const map = new Map<Square, Square[]>();
    for (const [from, toList] of Object.entries(legalMovesByFrom)) {
      map.set(from as Square, toList as Square[]);
    }
    return map;
  }, [legalMovesByFrom]);

  return (
    <div style={{ width: 560 }}>
      <ChessiroCanvas position={fen} dests={dests} onMove={onMove} />
    </div>
  );
}

Controlled arrows and marks

import { useState } from 'react';
import { ChessiroCanvas, type Arrow } from 'chessiro-canvas';

function AnalysisBoard({ fen }: { fen: string }) {
  const [arrows, setArrows] = useState<Arrow[]>([]);
  const [marks, setMarks] = useState<string[]>([]);

  return (
    <div style={{ width: 560 }}>
      <ChessiroCanvas
        position={fen}
        arrows={arrows}
        onArrowsChange={setArrows}
        markedSquares={marks}
        onMarkedSquaresChange={setMarks}
      />
    </div>
  );
}

Theme and piece assets

<ChessiroCanvas
  position={fen}
  theme={{
    id: 'wood',
    name: 'Wood',
    darkSquare: '#8B5A2B',
    lightSquare: '#F0D9B5',
    margin: '#5C3B1F',
    lastMoveHighlight: '#E7C15D',
    selectedPiece: '#A86634',
  }}
  pieceSet={{
    id: 'alpha',
    name: 'Alpha',
    path: '/pieces/alpha',
  }}
/>

Benchmark vs react-chessboard

Latest benchmark file: benchmarks/latest.json Latest browser benchmark file: benchmarks/browser/latest.json

Run Node benchmark:

npm run benchmark

Run browser benchmark (Playwright + Chromium, local vs origin/main vs react-chessboard):

npm run benchmark:browser

Quick browser benchmark:

npm run benchmark:browser:quick

Method:

• Environment: Node v25.6.1, macOS arm64, Apple M4 (10 cores), 16 GB RAM
• 8 measured rounds + 2 warmup rounds
• 300 position updates per round
• Position updates replay multiple real move-playthrough scenarios (castling, captures, endgames, promotion)
• Same board size (640px) and animations disabled for both libraries
• Metrics: mount wall time, update wall time, React Profiler update duration, bundle gzip
• Harnesses: scripts/benchmark.mjs (Node) and scripts/benchmark-playwright.mjs (browser)

Run a subset of scenarios:

BENCH_SCENARIOS=italian-castling,sicilian-captures npm run benchmark
BENCH_SCENARIOS=italian-castling,sicilian-captures npm run benchmark:browser

Results (generated on 2026-02-24 UTC):

| Metric | chessiro-canvas | react-chessboard | Delta | | --- | ---: | ---: | ---: | | Mount wall time (mean) | 3.13 ms | 14.23 ms | 78.0% faster | | Update wall time (mean, 300 renders) | 277.42 ms | 733.11 ms | 62.2% faster | | Update wall per render (mean) | 0.92 ms | 2.44 ms | 62.2% faster | | React Profiler update duration (mean) | 0.22 ms | 1.33 ms | 83.4% faster | | Bundle ESM gzip | 31.41 KB | 37.38 KB | 16.0% smaller |

Notes:

• Numbers will vary by machine, Node version, and benchmark config.
• This benchmark is for relative comparison under the same harness, not an absolute browser FPS claim.

Development

npm install
npm run dev
npm run docs:dev
npm run build
npm run typecheck
npm run benchmark

License

MIT