cm-chessboard

Extensions allow you to hook into the chessboard lifecycle. An extension must extend the Extension class and can register for specific EXTENSION_POINT events.

Available Extension Points:

• positionChanged: Piece positions changed.
• boardChanged: Board orientation changed.
• moveInputToggled: Move input enabled/disabled.
• moveInput: Move lifecycle (start, moving, validating, cancel).
• beforeRedrawBoard / afterRedrawBoard: Around board redraws.
• animation: Animation lifecycle (start, end, frames).
• destroy: Before the board is destroyed.

How to add an extension:

1. Define a class extending Extension.
2. Use this.registerExtensionPoint(name, callback) in the constructor.
3. Pass the extension class in the Chessboard constructor props.

class MyCoolChessboardExtension extends Extension {
    constructor(chessboard, props) {
        super(chessboard, props)
        this.registerExtensionPoint(EXTENSION_POINT.moveInput, (data) => {
            console.log(data)
        })
    }
}

const chessboard = new Chessboard(document.getElementById("board"), {
    extensions: [{
        class: MyCoolChessboardExtension,
        props: { /* config */ }
    }]
})

Marker types are matched by object reference, not by structural equality. This means that even if two marker type objects have identical properties, they are treated as different types if they are not the exact same object in memory.

Crucial Rules:

1. Use Constants: Always define your marker types as module-level constants.
2. Reuse References: Pass the exact same reference to addMarker and removeMarkers.
3. Avoid Cloning: Do not clone marker types (e.g., via JSON.parse(JSON.stringify(type)) or by storing them in a framework state that performs deep-copying), as the reference will break and removeMarkers will fail to find a match.

If you use the built-in MARKER_TYPE constants, import them once and reuse that specific reference.

// ✅ CORRECT: Using the same reference
const myType = {class: "marker-frame", slice: "markerFrame"};
board.addMarker(myType, "e4");
board.removeMarkers(myType); // Successfully removed

// ❌ INCORRECT: Different references, even if they look identical
board.addMarker({class: "marker-frame", slice: "markerFrame"}, "e4");
board.removeMarkers({class: "marker-frame", slice: "markerFrame"}); // Silently does nothing

By default, the chessboard is read-only. To allow users to move pieces via click or drag, you must:

1. Use an extension: It is recommended to use the Markers extension to improve the visual experience of moving pieces.
2. Call enableMoveInput(handler): Pass a callback function that handles move events.
3. Handle events: The handler receives an event object. Returning true allows the move, while returning false cancels it. Use INPUT_EVENT_TYPE to check the event state.

import {Chessboard, FEN, INPUT_EVENT_TYPE} from "./path/to/Chessboard.js"
import {Markers} from "./path/to/extensions/markers/Markers.js"

const board = new Chessboard(document.getElementById("board"), {
    position: FEN.start,
    assetsUrl: "../assets/",
    extensions: [{class: Markers}]
})

board.enableMoveInput(inputHandler)

function inputHandler(event) {
    console.log(event)
    if(event.type === INPUT_EVENT_TYPE.moveInputStarted || 
       event.type === INPUT_EVENT_TYPE.validateMoveInput) {
        return true // true allows the move, false cancels it
    }
}

You can create custom markers by defining an object that maps a CSS class for styling to an SVG slice ID for the visual shape.

Marker Object Schema

An object must contain:

• class: The CSS class used to style the marker (e.g., setting stroke, opacity, etc.).
• slice: The id of the <g> element within sprite.svg that defines the marker's shape.

Implementation Example

To create a red circle marker, you would define a CSS class .marker-circle-red and use the existing markerCircle slice from the SVG.

/* Define the visual style */
marker.marker-circle-red {
    stroke: #aa0000;
    stroke-width: 3px;
    opacity: 0.4;
}

// Define the custom marker type
const myMarkerType = { class: "marker-circle-red", slice: "markerCircle" };

// Use it on the board
chessboard.addMarker(myMarkerType, "e4");

// Remove specific instances
chessboard.removeMarkers(myMarkerType, "e4");

// Remove all markers of this custom type
chessboard.removeMarkers(myMarkerType);

const myMarkerType = {class: "marker-circle-red", slice: "markerCircle"}
// add
chessboard.addMarker(myMarkerType, "e4")
// remove a specific marker
chessboard.removeMarkers(myMarkerType, "e4")
// remove all "myMarkerType"
chessboard.removeMarkers(myMarkerType)
// remove all markers
chessboard.removeMarkers()