Chessboard Vue

A chess board component for Vue JS (>= 3), written in Typescript.

Usage

With your package manager, add the 'chessboard-vue' package (e.g bun add chessboard-vue)
In you main.js add the following content :

import ChessboardVueComponent from "chessboard-vue";
import "chessboard-vue/dist/style.css";

Don't forget to use the component (in the same file), e.g :

createApp(App)
  .use(ChessboardVueComponent) //add this line
  .use(pinia)
  .use(router);

You can use the ChessboardVue component from any template in your project. E.g :

<ChessboardVue
  :size="500"
  ref="board"
  @checkmate="handleCheckmate"
  @move-done="addHistoryMove"
  :reversed="reversed"
/>

Documentation

Attributes

Name	Purpose	Type	Default
size	Defines the common width and height of the board, in pixels.	number	100
reversed	Says if the black side is at bottom of the board.	boolean	false
background	Defines the overall background color of the board.	string	#124589
coordinatesVisible	Says if the coordinates (around the cells) are visible.	boolean	true
coordinatesColor	Defines the text color of the coordinates.	string	yellow
whiteCellsColor	Defines the color of the white cells.	string	navajowhite
blackCellsColor	Defines the color of the black cells.	string	peru
originCellColor	Defines the color of the origin cell when performing a drag and drop for a move.	string	crimson
targetCellColor	Defines the color of the target cell when performing a drag and drop for a move.	string	ForestGreen
dndCrossCellColor	Defines the color of the indicator cross cells when performing a drag and drop for a move.	string	DimGrey
moveHighlightColor	Defines the color of the last move arrow.	string	CadetBlue
lastMoveVisible	Says if the last move arrow must be visible.	boolean	true
whitePlayerHuman	Says if the white side accepts a move from the user, of if it should be handled manually with the playManualMove method.	boolean	true
blackPlayerHuman	Says if the black side accepts a move from the user, of if it should be handled manually with the playManualMove method.	boolean	true

Methods

newGame

Starts a new game with the given position in Forsyth-Edwards Notation. If the startPositionFen string is not given, will use the default chess start position.

Field name	Purpose	Type	Default
startPositionFen	Defines the position, in Forsth-Edwards Notation, that must be use.	string	rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

This method does not return anything.

stop

Stops the current game, even if it has not been stopped logically yet.

This method does not take any parameter, and does not return anything.

isWhiteTurn

Says, if the turn is to white side, as a boolean.

This method does not take any parameter.

playManualMove

Plays a move manually, without user interaction. This method won't have any effect is game is not in progress, or if the side in turn is defined as a human player.

If the parameter inputMove is given a string, it must conform to the Long Algebraic Notation. Otherwise, it can be an object with the following keys : "from" as the start cell string (e.g: "a4"), "to" as the end cell string, and "promotion" still an optional letter which can be one of "q", "r", "b" or "n".

Field name	Purpose	Type	Default
inputMove	Defines the move to be applied.	string \| { from : string ; to : string ; promotion ? : string }	Not defined

This method returns if the call succeed, as a boolean.

gameIsInProgress

Says if the game is in progress, as a boolean.

This method does not take any parameter.

setStartPosition

Sets the start position of the game in the board, but only if the game is not in progress. It returns a boolean indicated the success of the call.

This method does not take any parameter.

It can be useful in order to define an history component and make it interact with the board. Don't forget to check the event @moveDone below.

setPositionAndLastMove

Sets the current position of the game in the board, but only if the game is not in progress. It returns a boolean indicated the success of the call.

The type Move is defined in the Chessboard.vue file (so can be imported too), and means the following :

export interface Move {
  start: Cell;
  end: Cell;
}

where Cell is also defined in the Chessboard.vue file and means the following :

export interface Cell {
  file: number,
  rank: number,
}

Forsyth-Edwards Notation is explained there.

Field name	Purpose	Type	Default
positionFen	Defines the position to be set in Forsyth-Edwards Notation.	string	Not defined
move	Defines the last move arrow to be set values.	Move	Not defined

It can be useful in order to define an history component and make it interact with the board. Don't forget to check the event @moveDone below.

getCurrentPosition

Returns the current position of the board, in the format Forsyth-Edwards Notation as a string.

This method does not take any parameter.

setLastBoardArrow

Sets the last board arrow, it can even be when the game is in progress.

This method does not return anything.

The type Move is defined in the Chessboard.vue file (so can be imported too), and means the following :

export interface Move {
  start: Cell;
  end: Cell;
}

where Cell is also defined in the Chessboard.vue file and means the following :

export interface Cell {
  file: number,
  rank: number,
}

Field name	Purpose	Type	Default
move	The coordinates of the last move arrow.	Move	Not defined

Events

checkmate

Happens when a checkmate has been done on the board.

Given field name	Purpose	Type
byWhite	Says it the checkmate has been administrated by white side.	boolean