2. Basic Method options

0. Basic Example

// Initialize Chessboard widget
var board = Chessboard('myBoard', 'start');

// --- 1. Position & Board State ---

// Returns the current position as a FEN string
var currentFen = board.fen();

// Executes one or more moves on the board
board.move('e2-e4', 'e7-e5');

// Returns the current position as a Position Object
var posObj = board.position();

// Animates the board to a new position (FEN string)
board.position('rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1', true);

// Resets the board to the initial starting position
board.start(true);

// Removes all pieces from the board
board.clear(true);

// Removes the widget, event listeners, and DOM nodes
board.destroy();


// --- 2. Viewport & Orientation ---

// Flips the board orientation
board.flip();

// Returns the current orientation of the board ('white' or 'black')
var currentOrientation = board.orientation();

// Sets the board orientation specifically to black
board.orientation('black');

// Recalculates sizes based on the parent element and redraws
board.resize();


// --- 3. Square Highlighting (New!) ---

// Highlights a specific square with custom styles
board.highlightSquare('e4', { backgroundColor: 'yellow', opacity: 0.5 });

// Removes custom highlight from a specific square
board.removeHighlight('e4');

// Clears all active square highlights from the board
board.clearHighlights();


// --- 4. Shape (New!) ---

// Draws an arrow overlay from e2 to e4
board.addArrow('e2', 'e4', { color: 'blue', width: 4 });

// Removes the arrow between e2 and e4
board.removeArrow('e2', 'e4');

// Adds a circle mark onto square d4
board.addMark('d4', 'circle', { color: 'red', fill: true });

// Removes the mark from square d4
board.removeMark('d4');

// Clears all shapes (arrows and marks) from the board
board.clearShapes();

---

1. Position & Board State

fen()

• Arguments: none
• Description: Returns the current position as a FEN string. Alias of position('fen').
• Example: Get Position

move(fromsquare1-tosquare1, fromsquare2-tosquare2, ...)

• Arguments: 'e2-e4', 'g8-f6', etc
• Description: Executes one or more moves on the board. Returns an updated Position Object of the board including the move(s).
• Example: Move Pieces

position(fen)

• Arguments: 'fen' (optional)
• Description: Returns the current position as a Position Object. If the first argument is 'fen', returns the position as a FEN string.
• Example: Get Position

position(newPosition, useAnimation)

• Arguments: Position Object, FEN string, or 'start' / useAnimation (Boolean, optional, default: true)
• Description: Animates to a new position. If useAnimation is false, sets the position instantly.
• Example: Set Position

start(useAnimation)

• Arguments: useAnimation (Boolean, optional, default: true)
• Description: Sets the board to the start position. If useAnimation is false, sets the position instantly. Alias of position('start') and position('start', false).
• Example: Set Position

clear(useAnimation)

• Arguments: useAnimation (Boolean, optional, default: true)
• Description: Removes all the pieces on the board. If useAnimation is false, removes pieces instantly. Alias of position({}) and position({}, false).
• Example: Clear Board

destroy()

• Arguments: none
• Description: Removes the widget, event listeners, and created DOM nodes from the DOM.
• Example: Destroy Board

---

2. Viewport & Orientation

flip()

• Arguments: none
• Description: Flips the board orientation. Alias of orientation('flip').
• Example: Orientation

orientation()

• Arguments: none
• Description: Returns the current orientation of the board.
• Example: Orientation

orientation(side)

• Arguments: 'white', 'black', or 'flip'
• Description: If 'white' or 'black', sets the orientation of the board accordingly. If 'flip', flips the orientation.
• Example: Orientation

resize()

• Arguments: none
• Description: Recalculates board and square sizes based on the parent element and redraws the board accordingly.
• Example: Resize

---

3. Square Highlighting (New!)

highlightSquare(square, styleOptions) (New!)

• Arguments: square (String), styleOptions (Object, optional)
• Description: Highlights a specific square on the board. Supports options such as backgroundColor, border, opacity, and className. Multiple simultaneous square-specific styles are supported and persist across redraws (resize, flip, orientation redraw, etc.).
• Example: board.highlightSquare('e4', { backgroundColor: 'yellow' })

removeHighlight(square) (New!)

• Arguments: square (String)
• Description: Removes the custom highlight from the specified square.
• Example: board.removeHighlight('e4')

clearHighlights() (New!)

• Arguments: none
• Description: Clears all active square highlights from the board.
• Example: board.clearHighlights()

---

4. Shape (New!)

addArrow(fromsquare, tosquare, options) (New!)

• Arguments: fromsquare (String), tosquare (String), options (Object, optional)
• Description: Draws an arrow overlay from one square to another using a non-blocking SVG layer (pointer-events: none). Supports options: color, opacity, width, and headSize. Automatically maintains correct coordinates after flip() and resize().
• Example: board.addArrow('e2', 'e4', { color: 'blue', width: 4 })

removeArrow(fromsquare, tosquare) (New!)

• Arguments: fromsquare (String), tosquare (String)
• Description: Removes an arrow between the specified source and destination squares.
• Example: board.removeArrow('e2', 'e4')

addMark(square, type, options) (New!)

• Arguments: square (String), type ('circle', 'cross', or 'square'), options (Object, optional)
• Description: Adds a visual shape mark onto a square on the board's SVG overlay layer. Supports options: color, opacity, radius/size, fill, stroke, and strokeWidth.
• Example: board.addMark('d4', 'circle', { color: 'red', fill: true })

removeMark(square) (New!)

• Arguments: square (String)
• Description: Removes the visual mark on the specified square.
• Example: board.removeMark('d4')

clearShapes() (New!)

• Arguments: none
• Description: Clears all shapes (both arrows and marks) from the board's SVG overlay layer.
• Example: board.clearShapes()