Documentation

styles

CSSResult

position

{ [square: string]: string | undefined; }

The current position of the board, as a PositionObject. This property may
be set externally, but only to valid PositionObjects. The value is copied
before being applied to the board. Changes to the position object are not
reflected in th rendering.

To set the position using FEN, or a keyword like 'start', or to use
animations, use the setPosition method.

hideNotation

boolean

Whether to show the board notation.

showNotation

boolean

Whether to show the board notation. This is always the inverse of
hideNotation, which reflects the hide-notation attribute.

orientation

"black" | "white"

The orientation of the board. 'white' for the white player at the bottom,
'black' for the black player at the bottom.

draggablePieces

boolean

If true, pieces on the board are draggable to other squares.

dropOffBoard

"trash" | "snapback"

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.

This property has no effect when draggable is false.

pieceTheme

string | ((piece: string) => string) | undefined

A template string or function used to determine the source of piece images,
used by the default renderPiece function, which renders an <img>
element.

If pieceTheme is a string, the pattern {piece} will be replaced by the
piece code. The result should be an an <img> source.

If pieceTheme is a function the first argument is the piece code. The
function should return an <img> source.

renderPiece

RenderPieceFunction | undefined

A function that renders DOM for a piece to a container element. This
function can render any elements and text, including SVG.

The default value renders an SVG image of the piece, unless the
pieceTheme property is set, then it uses pieceTheme to get the URL for
an <img> element.

moveSpeed

number | "fast" | "slow"

Animation speed for when pieces move between squares or from spare pieces
to the board.

snapbackSpeed

number | "fast" | "slow"

Animation speed for when pieces that were dropped outside the board return
to their original square.

snapSpeed

number | "fast" | "slow"

Animation speed for when pieces "snap" to a square when dropped.

trashSpeed

number | "fast" | "slow"

Animation speed for when pieces are removed.

appearSpeed

number | "fast" | "slow"

Animation speed for when pieces appear on a square.

Note that the "appear" animation only occurs when sparePieces is false.

sparePieces

boolean

If true, the board will have spare pieces that can be dropped onto the
board. If sparePieces is set to true, draggablePieces gets set to
true as well.

setPosition

• position: string | PositionObject
• useAnimation:

Sets the position of the board.

fen

Returns the current position as a FEN string.

start

• useAnimation: boolean

Sets the board to the start position.

clear

• useAnimation: boolean

Removes all the pieces on the board. If useAnimation is false, removes
pieces instantly.

This is shorthand for setPosition({}).

move

• args: (string | false)[]

Executes one or more moves on the board.

Moves are strings the form of "e2-e4", "f6-d5", etc., Pass false as an
argument to disable animation.

flip

Flip the orientation.

resize

Recalculates board and square sizes based on the parent element and redraws
the board accordingly.

mouseover-square

CustomEvent

Fired when the cursor is over a square
The event's detail object has the following properties:

• square: the square that was entered
• piece: the piece on that square (or false if there is no piece)
• position: the current position
• orientation: the current orientation.

Note that mouseover-square will not fire during piece drag and drop.
Use drag-move instead.

mouseout-square

CustomEvent

Fired when the cursor exits a square
The event's detail object has the following properties:
square: the square that was left
piece: the piece on that square (or false if there is no piece)
position: the current position
orientation: the current orientation.

Note that mouseout-square will not fire during piece drag and drop.
Use drag-move instead.

snapback-end

CustomEvent

Fired when the snapback animation is complete when
pieces are dropped off the board.
The event's detail object has the following properties:

• piece: the dragged piece
• square: the square the piece returned to
• position: the current position
• orientation: the current orientation.

snap-end

CustomEvent

Fired when a piece completes a snap animation
The event's detail object has the following properties:

• source: the source of the dragged piece
• square: the target of the dragged piece
• piece: the dragged piece

drag-start

CustomEvent

Fired when a piece is picked up
The event's detail object has the following properties:

• source: the source of the piece
• piece: the piece
• position: the current position on the board
• orientation: the current orientation.

The drag action is prevented if the listener calls event.preventDefault().

drag-move

CustomEvent

Fired when a user-initiated drag moves
The event's detail object has the following properties:

• newLocation: the new location of the piece
• oldLocation: the old location of the piece
• source: the source of the dragged piece
• piece: the piece
• position: the current position on the board
• orientation: the current orientation.

drop

CustomEvent

Fired when a user-initiated drag ends
The event's detail object has the following properties:

• source: the source of the dragged piece
• target: the target of the dragged piece
• piece: the piece
• newPosition: the new position once the piece drops
• oldPosition: the old position before the piece was picked up
• orientation: the current orientation.
• setAction(action): a function to call to change the default action.
  If 'snapback' is passed to setAction, the piece will return to it's source square.
  If 'trash' is passed to setAction, the piece will be removed.

move-end

CustomEvent

Fired when a piece move completes
The event's detail object has the following properties:

• oldPosition: the old position
• newPosition: the new position

change

CustomEvent

Fired when the board position changes
The event's detail property has two properties:

• value: the new position
• oldValue: the old position

Warning: do not call any position-changing methods in your event
listener or you may cause an infinite loop. Position-changing methods
are: clear(), move(), position(), and start().

error

Event

Fired in the case of invalid attributes.

The background for white squares and text color for black squares

"#f0d9b5"

The background for black squares and text color for white squares

"#b58863"

The highlight color

"yellow"

The chess board

A square on the board

A chess piece

The spare piece container

The currently dragged piece

A white square

A black square

A highlighted square

The square location labels

The alpha (column) labels

The numeric (row) labels