gchessboard

API Reference

This page describes most attributes, fields, events, and CSS-related artifacts that can be used to customize gchessboard.

Attributes

Many aspects of the chessboard can be customized by simply setting HTML attributes.

<g-chess-board animation-duration="300"> </g-chess-board>

Each of the attributes described here also has a corresponding property (with a camel-cased name) that is accessible and modifiable via JavaScript.

const board = document.getElementById("id-of-board");
board.animationDuration = 300;
orientation

default "white"

What side's perspective to render squares from (what color appears on the bottom as viewed on the screen). Either "white" or "black".

turn

What side is allowed to move pieces. Either "white, "black", or unset. When unset, pieces from either side can be moved around.

interactive

default false

Whether the squares are interactive, i.e. user can interact with squares, move pieces etc. By default, this is false; i.e a board is only for displaying a position.

fen

FEN string representing the board position. Note that changes to the corresponding fen property will not reflect onto the "fen" attribute of the element. In other words, to get the latest FEN string for the board position, use the fen property.

Accepts the special string "start" as shorthand for the starting position of a chess game. An empty string represents an empty board. Invalid FEN values are ignored with an error.

Note that a FEN string normally contains 6 components, separated by slashes, but only the first component (the "piece placement" component) is used by this attribute.

coordinates

default "inside"

How to display coordinates for squares. Could be "inside" the board (default), "outside", or "hidden".

animation-duration

default 200

Duration, in milliseconds, of animation when adding/removing/moving pieces.

Other properties

The following properties accept non-primitive values (objects), and do not have a corresponding attribute.

position

A map-like object representing the board position, where object keys are square labels, and values are Piece objects. Note that changes to this property are mirrored in the value of the fen property of the element, but not the corresponding attribute. All changes to position are animated, using the duration specified by the animationDuration property.

Example:

board.position = {
  a2: {
    pieceType: "king",
    color: "white"
  },
  g4: {
    pieceType: "knight",
    color: "black"
  },
};
arrows

Set of arrows to draw on the board. This is an array of objects specifying arrow characteristics, with the following properties: (1) from and to corresponding to the start and end squares for the arrow, (2) optional weight for the line (values: "light", "normal", "bold"), and (3) brush, which is a string that will be used to make a CSS part where one can customize the color, opacity, and other styles of the arrow. For example, a value for brush of "foo" will apply a CSS part named arrow-foo to the arrow.

Note: because the value of brush becomes part of a CSS part name, it should be usable as a valid CSS identifier.

In addition to allowing arbitrary part names, arrows support a few out-of-the-box brush names, primary and secondary, which colors defined with CSS custom properties --arrow-color-primary and --arrow-color-secondary.

Example:

board.arrows = [
  { from: "e2", to: "e4" },
  {
    from: "g1",
    to: "f3",
    brush: "foo"
  },
  {
    from: "c7",
    to: "c5",
    brush: "secondary"
  },
];

Methods

addEventListener

Add listener for events on this element.

removeEventListener

Remove listener for an event on this element.

startMove

Start a move on the board at square, optionally with specified targets at targetSquares.

cancelMove

Imperatively cancel any in-progress moves.

Events

gchessboard fires a variety of events in response to user input. You can attach a listener to the <g-chess-board> object using addEventListener(). Events fired are of type CustomEvent, and contain a detail object with additional information about the user interaction.

movestart

Fired when the user initiates a move by clicking, dragging or via the keyboard.

The event has a detail object with the from and piece values for the move. It also has a function, setTargets(squares), that the caller can invoke with an array of square labels. This limits the set of targets that the piece can be moved to. Note that calling this function with an empty list will still allow the piece to be dragged around, but no square will accept the piece and thus it will always return to the starting square.

moveend

Fired when user is completing a move. This move can be prevented from completing by calling preventDefault() on the event. If that is called, the move itself remains in progress. The event has a detail object with from and to set to the square labels of the move, and piece containing information about the piece that was moved.

movefinished

Fired after a move is completed and animations are resolved. The event has a detail object with from and to set to the square labels of the move, and piece containing information about the piece that was moved.

The movefinished event is the best time to update board position in response to a move. For example, after a king is moved for castling, the rook can be subsequently moved by updating the board position in movefinished by setting the position property.

movecancel

Fired as a move is being canceled by the user. The event is itself cancelable, ie. a caller can call preventDefault() on the event to prevent the move from being canceled. Any pieces being dragged will be returned to the start square, but the move will remain in progress.

The event has a detail object with from set to the square label where the move was started, and piece containing information about the piece that was moved.

CSS properties

Use these properties to customize visual properties of the chessboard, such as square background, outline colors, and markers for move target squares.

--square-color-dark

default "hsl(145deg 32% 44%)"

Color for dark squares.

--square-color-light

default "hsl(51deg 24% 84%)"

Color for light squares.

--square-color-dark-hover

default "hsl(144deg 75% 44%)"

Hover color for a dark square. Applied when mouse is hovering over an interactable square or a square has keyboard focus during a move.

--square-color-light-hover

default "hsl(52deg 98% 70%)"

Hover color for a dark square. Applied when mouse is hovering over an interactable square or a square has keyboard focus during a move.

--square-color-dark-active

default "hsl(142deg 77% 43%)"

Color applied to dark square when it is involved in (the starting point) of a move. By default this color is similar to, but slightly different from, --square-color-dark-hover.

--square-color-light-active

default "hsl(50deg 95% 64%)"

Color applied to light square when it is involved in (the starting point) of a move. By default this color is similar to, but slightly different from, --square-color-light-hover.

--outline-color-dark-active

default "hsl(138deg 85% 53% / 95%)"

Color of outline applied to dark square when it is the starting point of a move. It is applied in addition to --square-color-dark-active, and is visible when the square does not have focus.

--outline-color-light-active

default "hsl(66deg 97% 72% / 95%)"

Color of outline applied to light square when it is the starting point of a move. It is applied in addition to --square-color-light-active, and is visible when the square does not have focus.

--outline-color-focus

default "hsl(30deg 94% 55% / 90%)"

Color of outline applied to square when it has focus.

--outer-gutter-width

default "4%"

When the coordinates property is outside, this CSS property controls the width of the gutter outside the board where coords are shown.

--inner-border-width

default "1px"

Width of the inside border drawn around the board.

--inner-border-color

default "var(--square-color-dark)"

Color of the inside border drawn around the board.

--move-target-marker-color-dark-square

default "hsl(144deg 64% 9% / 90%)"

Color of marker shown on dark square when it is an eligible move target.

--move-target-marker-color-light-square

default "hsl(144deg 64% 9% / 90%)"

Color of marker shown on light square when it is an eligible move target.

--move-target-marker-radius

default "24%"

Radius of marker on a move target square.

--move-target-marker-radius-occupied

default "82%"

Radius of marker on a move target square that is occupied (by a piece or custom content).

--outline-blur-radius

default "3px"

Blur radius of all outlines applied to square.

--outline-spread-radius

default "4px"

Spread radius of all outlines applied to square.

--coords-font-size

default "0.7rem"

Font size of coord labels shown on board.

--coords-font-family

default "sans-serif"

Font family of coord labels shown on board.

--coords-inside-coord-padding-left

default "0.5%"

Left padding applied to coordinates when shown inside the board. Percentage values are relative to the width of the board.

--coords-inside-coord-padding-right

default "0.5%"

Right padding applied to coordinates when shown inside the board. Percentage values are relative to the width of the board.

--ghost-piece-opacity

default 0.35

Opacity of ghost piece shown while dragging. Set to 0 to hide ghost piece altogether.

--piece-drag-z-index

default 9999

Z-index applied to piece while being dragged.

--piece-drag-coarse-scale

default 2.4

Amount to scale up a piece when doing a coarse (touch) drag. On mobile devices, pieces will be scaled up in size to make them easier to see.

--piece-padding

default "3%"

Padding applied to square when piece is placed in it.

--arrow-color-primary

default "hsl(40deg 100% 50% / 80%)"

Color applied to arrow with brush primary.

--arrow-color-secondary

default "hsl(7deg 93% 61% / 80%)"

Color applied to arrow with brush secondary.

CSS parts

gchessboard provides a collection of CSS parts to customize the images used for chess pieces on the board, as well as brush color, opacity, and other styles associated with arrows drawn on the board.

piece-<b|w><b|r|p|n|k|q>

CSS parts for each of the piece classes. The part name is of the form piece-xy, where x corresponds to the color of the piece -- either w for white or b for black, and y is the piece type -- one of p (pawn), r (rook), n (knight), b (bishop), k (king), q (queen). Thus, piece-wr would be the CSS part corresponding to the white rook.

The CSS parts can be used to set custom CSS for the pieces (such as changing the image for a piece by changing the background-image property).

arrow-<brush_name>

CSS parts for any arrow brushes configured using the brush field on an arrow specification (see the arrows property for more details).

<g-chess-board fen="start" id="custom-board">
</g-chess-board>
<script type="module">
document.getElementById("custom-board").arrows = [
  // The brush name can later be referenced in styles
  { from: "d2", to: "d4", brush: "custom-arrow" },
];
</script>
<style>
  /* Style for (b)lack (q)ueen */
  #custom-board::part(piece-bq) {
    background-image: url("../images/crown.jpg");
  }
  /* Style for arrow with brush name "custom-arrow" */
  #custom-board::part(arrow-custom-arrow) {
    color: fuchsia;
  }
</style>

Slots

gchessboard provides the ability to place arbitrary content on squares using named slots. Each square has a slot corresponding to its algebraic label (such as a1 or g3). Any nested element within <g-chess-board> with a slot attribute set to a square label will have its content placed on the correct square.

Slotted elements appear behind pieces by default, so they provide a simple way to set a square background color using an empty <div> element with full height.

<g-chess-board fen="8/8/8/8/2R5/8/8/8" interactive>

  <div slot="e5">
    <svg viewBox="0 0 10 10" stroke="black" fill="none">
      <ellipse cx="5" cy="5" rx="4" ry="3" />
    </svg>
  </div>
  <div slot="c3">
    <svg viewBox="0 0 10 10" stroke="goldenrod" fill="none">
      <polygon points="1,5 4,2 8,7" />
    </svg>
  </div>
  <div slot="c4" style="background-color: firebrick; height: 100%;"></div>
</g-chess-board>