@echecs/react-movesheet

React move notation panel — displays chess game moves with click navigation, variations, comments, NAGs, evaluation, clock, and keyboard navigation. Inline styles with CSS variable theming, zero dependencies beyond React and @echecs/pgn.

Installation

npm install @echecs/react-movesheet
# or
pnpm add @echecs/react-movesheet

React >=18 is a peer dependency.

Quick start

Minimal

import parse from '@echecs/pgn';
import { MoveSheet } from '@echecs/react-movesheet';

const [game] = parse('1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 *');

export function App() {
  return <MoveSheet game={game} />;
}

With navigation

import { useState } from 'react';
import parse from '@echecs/pgn';
import { MoveSheet } from '@echecs/react-movesheet';

const [game] = parse('1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 *');

export function App() {
  const [moveId, setMoveId] = useState<string | undefined>();

  return (
    <MoveSheet
      currentMoveId={moveId}
      game={game}
      onSelectMove={setMoveId}
      showComments
      showNags
    />
  );
}

Props

Prop	Type	Default	Description
game	PGN	required	Parsed PGN game from @echecs/pgn
currentMoveId	string	undefined	ID of the currently active move
onSelectMove	(moveId: string) => void	—	Called when a move is clicked
showComments	boolean	true	Show inline comment text
showEvaluation	boolean	false	Show engine evaluation after moves
showNags	boolean	true	Show NAG glyphs (!, ?, !!, ??)
showClock	boolean	false	Show clock times
keyboard	boolean	true	Enable arrow key navigation

Keyboard navigation

When keyboard is enabled and the panel is focused:

Key	Action
Right	Next move (main continuation)
Left	Previous move
Down	Enter variation / cycle between variations
Up	Exit variation (jump to move before the branch)
Home	First move
End	Last move in current line

CSS variable theming

All colours are controlled via CSS custom properties on a parent element:

<div
  style={{
    '--movesheet-background': '#1a1a2e',
    '--movesheet-move-text': '#e0e0e0',
    '--movesheet-active-move': '#3a5a8c',
    '--movesheet-comment': '#8899aa',
    '--movesheet-nag': '#cc8844',
    '--movesheet-evaluation': '#6699cc',
    '--movesheet-variation': '#7788aa',
    '--movesheet-move-number': '#556677',
  }}
>
  <MoveSheet game={game} />
</div>

Variable	Default	Description
--movesheet-background	transparent	Panel background
--movesheet-active-move	#d4e8ff	Active move bg
--movesheet-move-text	inherit	Move SAN colour
--movesheet-move-number	inherit	Move number colour
--movesheet-comment	#666	Comment text colour
--movesheet-nag	inherit	NAG glyph colour
--movesheet-evaluation	gray	Eval text colour
--movesheet-variation	#888	Variation text colour

Utilities

The package also exports tree utilities for advanced use:

import { buildTree, findNode, pathToNode } from '@echecs/react-movesheet';
import type { MoveNode } from '@echecs/react-movesheet';

const root = buildTree(game);
const node = findNode(root, 'm3w');
const path = pathToNode(root, 'm3w'); // [root, m1w, m1b, m2w, m2b, m3w]

License

MIT