Skip to content

1. Config Properties

Jump to bottom
hyeongi-park edited this page Jul 27, 2026 · 1 revision

0. Basic Example

var config = {
  draggable: true, // If true, pieces on the board are draggable to other squares
  dropOffBoard: 'snapback', // If 'snapback', pieces dropped off the board return to their original square; if 'trash', they are removed
  position: 'start', // Sets the initial position of the board ('start', FEN String, or Position Object)
  interactiveShapes: false, // If true, enables interactive shapes: right-click draws a circle marker, and right-click drag draws an arrow.
  onChange: function(oldPos, newPos) {
    // Fires when the board position changes (oldPos to newPos)
  },
  onDragStart: function(source, piece, position, orientation) {
    // Fires when a piece is picked up; return false to prevent the drag action
  },
  onDragMove: function(newLocation, oldLocation, source, piece, position, orientation) {
    // Fires when a dragged piece changes location
  },
  onDrop: function(source, target, piece, newPos, oldPos, orientation) {
    // Fires when a piece is dropped; return 'snapback' or 'trash' if needed
  },
  onMouseoutSquare: function(square, piece, position, orientation) {
    // Fires when the mouse leaves a square (does not fire during drag-and-drop)
  },
  onMouseoverSquare: function(square, piece, position, orientation) {
    // Fires when the mouse enters a square (does not fire during drag-and-drop)
  },
  onMoveEnd: function(oldPosition, newPosition) {
    // Fires at the end of animations when the board position changes
  },
  onSnapbackEnd: function(piece, square, position, orientation) {
    // Fires when the snapback animation is complete when pieces are dropped off the board
  },
  onSnapEnd: function(source, target, piece) {
    // Fires when the piece snap animation is complete
  },
  orientation: 'white', // Sets the initial orientation of the board ('white' or 'black')
  showNotation: true, // Turn board notation on or off
  sparePieces: false, // If true, the board will have spare pieces that can be dropped onto the board
  showErrors: 'console', // Controls how Chessboard reports errors (e.g., false, 'console', 'alert', or a function)
  pieceTheme: 'img/chesspieces/wikipedia/{piece}.png', // Template string or function used to determine piece image sources
  nagTheme: 'img/nags/custom/{nag}.png', // Template string or function used to determine nag image sources
  appearSpeed: 200, // Animation speed for when pieces appear on a square
  moveSpeed: 200, // Animation speed for when pieces move between squares or from spare pieces to the board
  snapbackSpeed: 50, // Animation speed for when pieces dropped outside the board return to their original square
  snapSpeed: 25, // Animation speed for when pieces snap to a square when dropped
  trashSpeed: 100 // Animation speed for when pieces are removed
};

var board = Chessboard('myBoard', config);

1. Board Behavior & Position

draggable

  • Type: Boolean
  • Default: false
  • Description: If true, pieces on the board are draggable to other squares.
  • Example: Draggable Snapback

dropOffBoard

  • Type: 'snapback' or 'trash'
  • Default: 'snapback'
  • Description:
    • If 'snapback', pieces dropped off the board will return to their original square.
    • If 'trash', pieces dropped off the board will be removed from the board.
    • Note: This property has no effect when draggable is false.
  • Example: Draggable Snapback | Draggable Trash

position

orientation

  • Type: 'white' or 'black'
  • Default: 'white'
  • Description: If provided, sets the initial orientation of the board.
  • Example: Orientation

showNotation

  • Type: Boolean
  • Default: true
  • Description: Turn board notation on or off.
  • Example: Notation

sparePieces

  • Type: Boolean
  • Default: false
  • Description: If true, the board will have spare pieces that can be dropped onto the board. (Setting this to true automatically sets draggable to true).
  • Example: Spare Pieces

interactiveShapes (New!)

  • Type: Boolean
  • Default: false
  • Description: If true, it enables interactive shapes where a right click draws a circle marker and a right click drag draws an arrow.

2. Event Handlers & Callbacks

onChange

  • Type: Function
  • Default: N/A
  • Description: Fires when the board position changes. The first argument is the old position, the second is the new position.

Warning: Do not call any position-changing methods (clear(), move(), position(), start()) inside your onChange function to prevent infinite loops.

onDragStart

  • Type: Function
  • Default: N/A
  • Description: Fires when a piece is picked up. Arguments: (source, piece, position, orientation). Return false to prevent the drag action.
  • Example: onDragStart | Prevent Drag

onDragMove

  • Type: Function
  • Default: N/A
  • Description: Fires when a dragged piece changes location. Arguments: (newLocation, oldLocation, source, piece, position, orientation).
  • Example: onDragMove

onDrop

  • Type: Function
  • Default: N/A
  • Description: Fires when a piece is dropped. Arguments: (source, target, piece, newPos, oldPos, orientation). Return 'snapback' to return the piece, or 'trash' to remove it.
  • Example: onDrop | Snapback | Trash

onMouseoutSquare & onMouseoverSquare

  • Type: Function
  • Default: N/A
  • Description: Fires when the mouse leaves/enters a square. Arguments: (square, piece, position, orientation). (Does not fire during drag-and-drop; use onDragMove instead).
  • Example: Highlight Legal Moves

onMoveEnd

  • Type: Function
  • Default: N/A
  • Description: Fires at the end of animations when the board position changes. Arguments: (oldPosition, newPosition).
  • Example: onMoveEnd

onSnapbackEnd

  • Type: Function
  • Default: N/A
  • Description: Fires when the "snapback" animation is complete. Arguments: (piece, square, position, orientation).
  • Example: onSnapbackEnd

onSnapEnd

  • Type: Function
  • Default: N/A
  • Description: Fires when the piece "snap" animation is complete. Arguments: (source, target, piece).
  • Example: Only Allow Legal Moves

3. Styling, Errors & Animations

pieceTheme

  • Type: String or Function
  • Default: 'img/chesspieces/wikipedia/{piece}.png'
  • Description: A template string or function used to determine the source of piece images.
  • Example: Piece Theme String | Function

nagTheme (New!)

  • Type: String or Function
  • Default: 'img/nags/chesscom/{nag}.png'
  • Description: A template string or function used to determine the source of NAG (Numeric Annotation Glyphs) images.

showErrors

  • Type: false or String or Function
  • Default: N/A
  • Description: Controls how Chessboard reports errors.
    • false: Ignore errors.
    • 'console': Send to console.log().
    • 'alert': Send to window.alert().
    • Function: Custom handler with arguments (code, errorString, data).

appearSpeed

  • Type: Number or 'slow' or 'fast'
  • Default: 200
  • Description: Animation speed when pieces appear on a square (Only occurs when sparePieces is false).

moveSpeed

  • Type: Number or 'slow' or 'fast'
  • Default: 200
  • Description: Animation speed for when pieces move between squares or from spare pieces to the board.
  • Example: Animation Speed

snapbackSpeed

  • Type: Number or 'slow' or 'fast'
  • Default: 50
  • Description: Animation speed for when pieces dropped outside the board return to their original square.
  • Example: Animation Speed

snapSpeed

  • Type: Number or 'slow' or 'fast'
  • Default: 25
  • Description: Animation speed for when pieces "snap" to a square when dropped.
  • Example: Animation Speed

trashSpeed

  • Type: Number or 'slow' or 'fast'
  • Default: 100
  • Description: Animation speed for when pieces are removed.
  • Example: Animation Speed

Clone this wiki locally