https://github.com/echecsjs/react-movesheet
React move notation panel — displays chess game moves with click navigation, variations, comments, NAGs, evaluation, and keyboard navigation.
https://github.com/echecsjs/react-movesheet
chess notation pgn react typescript
Last synced: 11 days ago
JSON representation
React move notation panel — displays chess game moves with click navigation, variations, comments, NAGs, evaluation, and keyboard navigation.
- Host: GitHub
- URL: https://github.com/echecsjs/react-movesheet
- Owner: echecsjs
- License: mit
- Created: 2026-04-05T11:16:37.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-22T13:38:46.000Z (20 days ago)
- Last Synced: 2026-06-22T15:18:37.393Z (20 days ago)
- Topics: chess, notation, pgn, react, typescript
- Language: TypeScript
- Homepage: https://github.com/echecsjs/react-movesheet#readme
- Size: 2.35 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# @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
```bash
npm install @echecs/react-movesheet
# or
pnpm add @echecs/react-movesheet
```
`react` >=18 and `@echecs/pgn` >=4 are peer dependencies.
## Quick start
### Minimal
```tsx
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 ;
}
```
### With navigation
```tsx
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();
return (
);
}
```
## 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 |
| `onContextMenu` | `(moveId: string) => void` | — | Called on right-click of a move |
| `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:
```tsx
```
| 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-comment-display` | `inline` | Comment display mode |
| `--movesheet-comment-font-style` | `italic` | Comment font style |
| `--movesheet-font-family` | `inherit` | Panel font family |
| `--movesheet-font-size` | `inherit` | Panel font size |
| `--movesheet-line-height` | `1.6` | Panel line height |
| `--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:
```tsx
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]
```
## Exported types
| Type | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| `Eval` | `{ type: 'cp' \| 'mate'; value: number; depth?: number }` — engine evaluation |
| `MoveNode` | Tree node representing a single move, with id, san, side, children, and optional eval/comment/nags/clock |
| `MoveSheetProps` | All props accepted by `` |
```tsx
import type { Eval, MoveNode, MoveSheetProps } from '@echecs/react-movesheet';
```
## License
MIT