Interactive example

A fast React chessboard built for real games.

Play against random legal moves, queue premoves while the opponent thinks, draw arrows with right-drag, and test the board API directly.

Your moveYou play White

0 moves

Black captured:

White captured:

Drag or click to move. Right-drag to draw an arrow.

Documentation

Learn the API by using it.

SwiftChess is a controlled React board powered by chess.js. Your application owns the game instance and FEN. The examples below are real boards, so you can test each prop while reading the matching code.

Installation

Install SwiftChess with chess.js. React 19 and React DOM 19 are peer dependencies, so add them explicitly in non-Next React apps.

Terminal

npm install swiftchess chess.js react@19 react-dom@19

Next.js: import swiftchess/style.css once in app/layout.tsx. Any component using the board must be a Client Component.

Quick start

Create one stable Chess instance, store its current FEN in state, and feed every position change back into the board.

Minimal controlled board

Move a piece. The board updates the FEN through onPositionChange while your component owns the state.

Live

chesspositiononPositionChangefillContainer

White to move

The state contract

01chess

The mutable chess.js game used to validate and apply moves.

02position

The FEN rendered by React. It should match chess.fen().

03onPositionChange

The callback that keeps your React state synchronized.

Do not create new Chess() on every render. Keep the instance stable with useState oruseRef.

Premoves and arrows

Premoves and user annotations work with internal state by default. UseoverlayArrows for engine or explorer hints that right-drag drawing should never mutate.

Guided premoves: Evans Gambit

Play the White moves. Black replies automatically, and during the delay you can queue the next highlighted move as a premove.

Live

premovesonPremovesChangeoverlayArrowsarrows

Step 1 of 5

Play 1. e4 to begin the Evans Gambit line.

Premove lifecycle

Use onPremoveAdd,onPremoveExecute, andonPremoveReject for UI or network updates.canQueuePremove can enforce your own rules.

Arrow interaction

Users draw and remove annotation arrows with right-drag. UseoverlayArrows for read-only host hints andonArrowCommit for add, remove, and clear events.

Analysis, themes, and sizing

Analysis mode supports ply-keyed move-classification badges. Presets provide a starting palette and boardTheme can override either square color.

Analysis presentation

Ply-keyed move badges, theme presets, overlay arrows, orientation, and responsive sizing can be combined.

Live

modemoveBadgesoverlayArrowsboardThemePresetflipped

Sizing option	Use it when
fillContainer	The board should responsively match its parent width.
boardSize	Your application controls the exact pixel size.
squareSize	Each square must have a fixed pixel size.
resizable	The user should resize the board with a drag handle.

Prop reference

The practical public API, grouped by responsibility. Onlychess andposition are required.

State and moves7 props↓

Prop	Type	Purpose
chess	Chess	Required chess.js instance. SwiftChess validates and applies moves to it.
position	string	Required current FEN. Update it from onPositionChange.
onPositionChange	(fen, move?) => void	Runs after a move, premove, reset, or FEN change.
onMove	(move) => void	Runs after a legal move with the chess.js Move object.
initialFen	string	Position restored by resetToInitialFen().
mode	'play' \| 'analysis'	Selects the board workflow. Default: play.
playerColor	'w' \| 'b'	Controls the player side and when premoves may be queued.

Premoves and arrows16 props↓

Prop	Type	Purpose
premoves	PremoveState[]	Controlled premove queue. Omit it to use internal state.
onPremovesChange	(premoves) => void	Receives the updated controlled premove queue.
onPremoveAdd	(premove) => void	Runs when a premove enters the queue.
onPremoveExecute	(premove, move) => void	Runs when a queued premove is played.
onPremoveReject	(premove) => void	Runs when a queued premove is no longer legal.
canQueuePremove	(args) => boolean	Adds application-specific premove validation.
relaxedPremoveMode	boolean	Allows natural premove targets before the opponent move resolves. Default: true.
overlayArrows	Arrow[]	Read-only host hints such as engine lines or explorer suggestions.
arrows	Arrow[]	Controlled user-drawn right-drag annotation arrows. Omit it to use internal state.
defaultArrows	Arrow[]	Initial uncontrolled user annotation arrows.
onArrowsChange	(arrows) => void	Receives the updated user annotation arrow list.
onArrowCommit	(event) => void	Receives add, remove, and clear lifecycle events for user arrows.
onLiveArrowChange	(arrow \| null) => void	Observes the transient right-drag preview.
arrowStyle	ArrowStyleOptions	Sets default committed user-arrow color, opacity, and width.
overlayArrowStyle	ArrowStyleOptions	Sets fallback style for overlay arrows.
liveArrowStyle	ArrowStyleOptions	Sets fallback style for the live preview arrow.

Layout and appearance16 props↓

Prop	Type	Purpose
boardThemePreset	BoardThemePreset	brownBoard, chessComClassic, iceBlue, or custom.
boardTheme	Partial<BoardThemeColors>	Overrides the preset light and/or dark square color.
flipped	boolean	Controls board orientation.
onFlippedChange	(flipped) => void	Runs when orientation changes inside the board.
moveBadges	MoveBadgeByPly[]	Shows host-provided move classifications keyed by visible ply.
lastMoveBadge	MoveBadge \| null	Simple latest-move badge override.
boardSize	number	Controlled board width and height in pixels.
squareSize	number	Fixes each square size; the board becomes squareSize x 8.
fillContainer	boolean	Measures the parent and fills its available width.
resizable	boolean	Displays the built-in resize handle.
minSize / maxSize	number	Minimum and maximum square size while resizing.
onBoardSizeChange	(boardSize, squareSize) => void	Runs when the rendered board size changes.
showLegalMoves	boolean	Shows legal destination markers. Default: true.
showStatusBar	boolean	Shows turn, check, and game-over status.
showCapturedPieces	boolean	Shows material captured by each side.
className	string	Class name for the board root wrapper.

Sound3 props↓

Prop	Type	Purpose
enableSounds	boolean	Enables built-in move, capture, castle, check, and end sounds.
successSoundSrc	string	URL for an optional application success sound.
playSuccessSound	boolean	Plays the success sound on a false-to-true change.

Ref API

Use a ChessBoardHandle ref for commands that are not naturally expressed as props.

Imperative controls

const boardRef = useRef<ChessBoardHandle>(null)

<ChessBoard
  ref={boardRef}
  chess={chess}
  position={position}
  onPositionChange={setPosition}
/>

boardRef.current?.flipBoard()
boardRef.current?.goToPreviousMove()
boardRef.current?.setPositionFromFen(fen)
boardRef.current?.resetToInitialFen()

flipBoard()

Toggle orientation.

setFlipped(value)

Set orientation directly.

isFlipped()

Read the current orientation.

goToPreviousMove()

Move backward in local board history.

goToNextMove()

Move forward in local board history.

canGoToPreviousMove()

Check whether backward navigation is available.

canGoToNextMove()

Check whether forward navigation is available.

setPositionFromFen(fen)

Validate and load a FEN. Returns true on success.

resetToInitialFen()

Restore initialFen. Returns true on success.

Exports and values

Import the component, types, and theme map fromswiftchess.

Runtime exports

ChessBoard, BOARD_THEME_PRESETS

Type exports

ChessBoardProps, ChessBoardHandle, ChessBoardMode, BoardThemePreset, BoardThemeColors, MoveBadge, MoveBadgeKind, PremoveState, PremoveValidationArgs, MoveBadgeByPly, Arrow, ArrowCommitEvent, LiveArrow, ArrowStyleOptions

Badge kinds: blunder, mistake, inaccuracy, miss, good, excellent, best, brilliant, book, and onlyMove.