Skip to content

feat: add clearArrowsOnPositionChange prop #218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Clariity merged 1 commit into from
Oct 18, 2025
Merged

feat: add clearArrowsOnPositionChange prop #218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 57 additions & 43 deletions docs/D_OptionsApi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import * as CanDragPieceStories from './stories/options/CanDragPiece.stories';
import * as ChessboardColumnsStories from './stories/options/ChessboardColumns.stories';
import * as ChessboardRowsStories from './stories/options/ChessboardRows.stories';
import * as ClearArrowsOnClickStories from './stories/options/ClearArrowsOnClick.stories';
import * as ClearArrowsOnPositionChangeStories from './stories/options/ClearArrowsOnPositionChange.stories';
import * as DarkSquareNotationStyleStories from './stories/options/DarkSquareNotationStyle.stories';
import * as DarkSquareStyleStories from './stories/options/DarkSquareStyle.stories';
import * as DragActivationDistanceStories from './stories/options/DragActivationDistance.stories';
Expand Down Expand Up @@ -53,49 +54,50 @@ The component has a number of options that you can use to customise the componen

The code for these examples can be viewed by clicking the "Show code" button in the bottom right of the interactive examples. The code can also be viewed in the [GitHub repository](https://github.com/Clariity/react-chessboard/tree/main/docs/stories/options).

| Option | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------------- |
| [allowAutoScroll](#optionsallowautoscroll) | Controls auto-scrolling when dragging pieces near window edges |
| [allowDragging](#optionsallowdragging) | Controls whether pieces can be dragged on the board |
| [allowDragOffBoard](#optionsallowdragoffboard) | Controls whether pieces can be dragged off the board |
| [allowDrawingArrows](#optionsallowdrawingarrows) | Controls whether arrows can be drawn by right-clicking and dragging |
| [alphaNotationStyle](#optionsalphanotationstyle) | Controls styling of the alpha notation (a-h) |
| [animationDurationInMs](#optionsanimationdurationinms) | Controls duration of piece movement animations |
| [arrows](#optionsarrows) | Array of arrows to display on the board |
| [arrowOptions](#optionsarrowoptions) | Controls styling and behavior of arrows |
| [boardOrientation](#optionsboardorientation) | Sets orientation of the board ('white' or 'black') |
| [boardStyle](#optionsboardstyle) | Controls styling of the main board container |
| [canDragPiece](#optionscandragpiece) | Function to determine if a piece can be dragged |
| [chessboardColumns](#optionschessboardcolumns) | Number of columns on the board |
| [chessboardRows](#optionschessboardrows) | Number of rows on the board |
| [clearArrowsOnClick](#optionscleararrowsonclick) | Controls whether arrows are cleared on board click |
| [darkSquareNotationStyle](#optionsdarksquarenotationstyle) | Controls styling of notation on dark squares |
| [darkSquareStyle](#optionsdarksquarestyle) | Controls styling of dark squares |
| [dragActivationDistance](#optionsdragactivationdistance) | Distance in pixels before drag activation |
| [draggingPieceGhostStyle](#optionsdraggingpieceghoststyle) | Controls styling of ghost piece while dragging |
| [draggingPieceStyle](#optionsdraggingpiecestyle) | Controls styling of piece being dragged |
| [dropSquareStyle](#optionsdropsquarestyle) | Controls styling of squares when dragging over them |
| [id](#optionsid) | Sets the id of the chessboard component |
| [lightSquareNotationStyle](#optionslightsquarenotationstyle) | Controls styling of notation on light squares |
| [lightSquareStyle](#optionslightsquarestyle) | Controls styling of light squares |
| [numericNotationStyle](#optionsnumericnotationstyle) | Controls styling of numeric notation (1-8) |
| [onArrowsChange](#optionsonarrowschange) | Handler for when internal arrows change |
| [onMouseOutSquare](#optionsonmouseoutsquare) | Handler for mouse leaving a square |
| [onMouseOverSquare](#optionsonmouseoversquare) | Handler for mouse entering a square |
| [onPieceClick](#optionsonpiececlick) | Handler for clicking a piece |
| [onPieceDrag](#optionsonpiecedrag) | Handler for starting to drag a piece |
| [onPieceDrop](#optionsonpiecedrop) | Handler for dropping a piece |
| [onSquareClick](#optionsonsquareclick) | Handler for clicking a square |
| [onSquareMouseDown](#optionsonsquaremousedown) | Handler for mouse button down on a square |
| [onSquareMouseUp](#optionsonsquaremouseup) | Handler for mouse button up on a square |
| [onSquareRightClick](#optionsonsquarerightclick) | Handler for right-clicking a square |
| [pieces](#optionspieces) | Object mapping piece types to React components |
| [position](#optionsposition) | Current position on the board (FEN string or position object) |
| [showAnimations](#optionsshowanimations) | Controls whether piece movements are animated |
| [showNotation](#optionsshownotation) | Controls whether board notation is displayed |
| [squareRenderer](#optionssquarerenderer) | Controls the rendering of squares on the board |
| [squareStyle](#optionssquarestyle) | Base styling applied to all squares |
| [squareStyles](#optionssquarestyles) | Object mapping squares to custom styles |
| Option | Description |
| ------------------------------------------------------------------ | ------------------------------------------------------------------- |
| [allowAutoScroll](#optionsallowautoscroll) | Controls auto-scrolling when dragging pieces near window edges |
| [allowDragging](#optionsallowdragging) | Controls whether pieces can be dragged on the board |
| [allowDragOffBoard](#optionsallowdragoffboard) | Controls whether pieces can be dragged off the board |
| [allowDrawingArrows](#optionsallowdrawingarrows) | Controls whether arrows can be drawn by right-clicking and dragging |
| [alphaNotationStyle](#optionsalphanotationstyle) | Controls styling of the alpha notation (a-h) |
| [animationDurationInMs](#optionsanimationdurationinms) | Controls duration of piece movement animations |
| [arrows](#optionsarrows) | Array of arrows to display on the board |
| [arrowOptions](#optionsarrowoptions) | Controls styling and behavior of arrows |
| [boardOrientation](#optionsboardorientation) | Sets orientation of the board ('white' or 'black') |
| [boardStyle](#optionsboardstyle) | Controls styling of the main board container |
| [canDragPiece](#optionscandragpiece) | Function to determine if a piece can be dragged |
| [chessboardColumns](#optionschessboardcolumns) | Number of columns on the board |
| [chessboardRows](#optionschessboardrows) | Number of rows on the board |
| [clearArrowsOnClick](#optionscleararrowsonclick) | Controls whether arrows are cleared on board click |
| [clearArrowsOnPositionChange](#optionscleararrowsonpositionchange) | Controls whether arrows are cleared on position change |
| [darkSquareNotationStyle](#optionsdarksquarenotationstyle) | Controls styling of notation on dark squares |
| [darkSquareStyle](#optionsdarksquarestyle) | Controls styling of dark squares |
| [dragActivationDistance](#optionsdragactivationdistance) | Distance in pixels before drag activation |
| [draggingPieceGhostStyle](#optionsdraggingpieceghoststyle) | Controls styling of ghost piece while dragging |
| [draggingPieceStyle](#optionsdraggingpiecestyle) | Controls styling of piece being dragged |
| [dropSquareStyle](#optionsdropsquarestyle) | Controls styling of squares when dragging over them |
| [id](#optionsid) | Sets the id of the chessboard component |
| [lightSquareNotationStyle](#optionslightsquarenotationstyle) | Controls styling of notation on light squares |
| [lightSquareStyle](#optionslightsquarestyle) | Controls styling of light squares |
| [numericNotationStyle](#optionsnumericnotationstyle) | Controls styling of numeric notation (1-8) |
| [onArrowsChange](#optionsonarrowschange) | Handler for when internal arrows change |
| [onMouseOutSquare](#optionsonmouseoutsquare) | Handler for mouse leaving a square |
| [onMouseOverSquare](#optionsonmouseoversquare) | Handler for mouse entering a square |
| [onPieceClick](#optionsonpiececlick) | Handler for clicking a piece |
| [onPieceDrag](#optionsonpiecedrag) | Handler for starting to drag a piece |
| [onPieceDrop](#optionsonpiecedrop) | Handler for dropping a piece |
| [onSquareClick](#optionsonsquareclick) | Handler for clicking a square |
| [onSquareMouseDown](#optionsonsquaremousedown) | Handler for mouse button down on a square |
| [onSquareMouseUp](#optionsonsquaremouseup) | Handler for mouse button up on a square |
| [onSquareRightClick](#optionsonsquarerightclick) | Handler for right-clicking a square |
| [pieces](#optionspieces) | Object mapping piece types to React components |
| [position](#optionsposition) | Current position on the board (FEN string or position object) |
| [showAnimations](#optionsshowanimations) | Controls whether piece movements are animated |
| [showNotation](#optionsshownotation) | Controls whether board notation is displayed |
| [squareRenderer](#optionssquarerenderer) | Controls the rendering of squares on the board |
| [squareStyle](#optionssquarestyle) | Base styling applied to all squares |
| [squareStyles](#optionssquarestyles) | Object mapping squares to custom styles |

## Options

Expand Down Expand Up @@ -380,6 +382,18 @@ Controls whether **internal** arrows are cleared when a square is clicked. If yo

<Canvas of={ClearArrowsOnClickStories.ClearArrowsOnClick} />

### `options.clearArrowsOnPositionChange`

Controls whether **internal** arrows are cleared when the position changes. If you are passing in external arrows via the [`arrows`](#optionsarrows) prop, these will not be automatically cleared when the position changes. Instead, you will need to clear them manually when updating the position and pass in a new value for the [`arrows`](#optionsarrows) prop.

**Default value:** `true`

**TypeScript type:** `boolean`

**Standard use case:** Disabling the ability to clear internal arrows when the position changes.

<Canvas of={ClearArrowsOnPositionChangeStories.ClearArrowsOnPositionChange} />

### `options.darkSquareNotationStyle`

Controls the styling of notation on dark squares. If you wish to instead hide the notation, set [`showNotation`](#optionsshownotation) to `false`.
Expand Down
1 change: 1 addition & 0 deletions docs/G_UpgradeToV5.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ The v5 release includes significant changes to the API. Here's a detailed compar
- `allowAutoScroll`: Controls whether dragging a piece near the edge of the window will automatically scroll the window
- `chessboardRows` and `chessboardColumns`: Control board dimensions
- `clearArrowsOnClick`: Control whether to clear arrows when clicking on the board
- `clearArrowsOnPositionChange`: Control whether to clear arrows when the position changes
- `dragActivationDistance`: Control the distance from the cursor to the piece to activate dragging
- `draggingPieceGhostStyle`: Style the ghost piece while being dragged
- `draggingPieceStyle`: Style the piece while being dragged
Expand Down
118 changes: 118 additions & 0 deletions docs/stories/options/ClearArrowsOnPositionChange.stories.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
import type { Meta, StoryObj } from '@storybook/react';
import { useState } from 'react';

import defaultMeta from '../basic-examples/Default.stories';
import { Chessboard } from '../../../src';

const meta: Meta<typeof Chessboard> = {
...defaultMeta,
title: 'stories/Options/ClearArrowsOnPositionChange',
} satisfies Meta<typeof Chessboard>;

export default meta;
type Story = StoryObj<typeof meta>;

export const ClearArrowsOnPositionChange: Story = {
render: () => {
const [clearArrowsOnPositionChange, setClearArrowsOnPositionChange] =
useState(true);
const [arrows] = useState([
{ startSquare: 'e2', endSquare: 'e4', color: 'red' },
{ startSquare: 'g1', endSquare: 'f3', color: 'blue' },
]);
const [position, setPosition] = useState(
'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR',
);

// generate random FEN position
function generateRandomFen() {
const pieces = [
'r',
'n',
'b',
'q',
'k',
'p',
'R',
'N',
'B',
'Q',
'K',
'P',
];
let fen = '';

// create 8 rows of random pieces
for (let i = 0; i < 8; i++) {
let emptyCount = 0;

// create 8 columns of random pieces or empty squares
for (let j = 0; j < 8; j++) {
if (Math.random() < 0.2) {
if (emptyCount > 0) {
fen += emptyCount;
emptyCount = 0;
}

fen += pieces[Math.floor(Math.random() * pieces.length)];
} else {
emptyCount++;
}
}

// add empty count to FEN string if there are empty squares
if (emptyCount > 0) {
fen += emptyCount;
}

// add slash between rows
if (i < 7) {
fen += '/';
}
}

// set the position
setPosition(fen);
}

// chessboard options
const chessboardOptions = {
arrows,
clearArrowsOnPositionChange,
id: 'clear-arrows-on-click',
position,
};

// render
return (
<div
style={{
display: 'flex',
flexDirection: 'column',
gap: '1rem',
alignItems: 'center',
}}
>
<label>
<input
type="checkbox"
checked={clearArrowsOnPositionChange}
onChange={(e) => setClearArrowsOnPositionChange(e.target.checked)}
/>
Clear arrows on position change
</label>

<button onClick={generateRandomFen}>
Generate random FEN position
</button>

<Chessboard options={chessboardOptions} />

<p style={{ fontSize: '0.8rem', color: '#666' }}>
Toggle the checkbox to enable/disable clearing arrows when the
position changes.
</p>
</div>
);
},
};
7 changes: 7 additions & 0 deletions src/ChessboardProvider.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,7 @@ export type ChessboardOptions = {
arrows?: Arrow[];
arrowOptions?: typeof defaultArrowOptions;
clearArrowsOnClick?: boolean;
clearArrowsOnPositionChange?: boolean;

// handlers
canDragPiece?: ({ isSparePiece, piece, square }: PieceHandlerArgs) => boolean;
Expand Down Expand Up @@ -255,6 +256,7 @@ export function ChessboardProvider({
arrows = [],
arrowOptions = defaultArrowOptions,
clearArrowsOnClick = true,
clearArrowsOnPositionChange = true,

// handlers
canDragPiece,
Expand Down Expand Up @@ -322,6 +324,11 @@ export function ChessboardProvider({
? fenStringToPositionObject(position, chessboardRows, chessboardColumns)
: position;

// clear internal arrows on position change
if (clearArrowsOnPositionChange) {
clearArrows();
}

// if no animation, just set the position
if (!showAnimations) {
setCurrentPosition(newPosition);
Expand Down