Chess Board Web Component

A comprehensive chess board component with support for piece rotation, fairy chess notation, keyboard navigation, and interactive editing. Perfect for chess problem compositions, position analysis, and chess applications.

Key Features

• Three-Button Mouse Editing: Primary click selects/moves, auxiliary click removes a piece, and context click emits a dedicated context event
• Piece Rotation: Rotate pieces in 45° increments using Alt/Option + Arrow keys
• Fairy Chess Notation: Add custom annotations for problem compositions
• Keyboard Navigation: Full keyboard support for piece placement and manipulation
• Board Orientation: Flip between white/black perspective with Shift+Arrow
• Clone & Invert Editing: Hold Shift to clone while moving, or Ctrl to clone and invert the color
• Responsive Design: Adapts to container size with CSS Container Queries
• FEN / FFEN Auto-Detect: Use the single fen attribute for either standard FEN or FFEN input, with automatic format detection

Interactive Demo - Try It Yourself!

Click on the board below to select a square, then try these keyboard shortcuts:

💡 Tip: Focus the board and experiment with all keyboard shortcuts to see the component in action!

Responsive Sizing

The chess board automatically adapts to its container size while maintaining a minimum size of 200px × 200px. The font size scales with the board using CSS Container Queries.

Small Board (300px)

Medium Board (400px)

Large Board (500px)

Board With Custom Size (11x11)

Board without Labels

Gray Themed Board

This board demonstrates how to customize the chess board colors using CSS custom properties. The gray-board class applies gray tones instead of the traditional brown colors. You can customize the board appearance by setting CSS variables like --cb-chess-light-square, --cb-chess-dark-square, --cb-chess-border-color, and --cb-chess-label-color.

Wood Themed Board

This board demonstrates a warm wood aesthetic perfect for a traditional chess experience. The wood-board class applies rich brown tones reminiscent of walnut and maple wood. The light squares use a honey-colored tone (#f4d7a8) while dark squares feature a deep brown (#8b5a2b), creating an elegant wooden chess board appearance. Custom CSS variables provide full control over the wood coloring with --cb-chess-light-square, --cb-chess-dark-square, --cb-chess-border-color, and --cb-chess-label-color.

Board Rotation (Black to Move)

This board automatically rotates 180 degrees when it's black's turn to move, based on the FEN string. The rotation provides a better viewing experience for the player whose turn it is. Compare this with the board above where white is to move.

Cell Click Events

The chess board dispatches a cellMainClick event when the main mouse button is used on a square, and also emits the legacy cellClick alias for backward compatibility. The event detail contains the square coordinate and piece information including rotation and fairy notation (if present). Click on any square below to see the event details.

// Listen for cell click events
const board = document.getElementById('clickable-board');
const output = document.getElementById('click-output');

board.addEventListener('cellClick', (event) => {
  const { square, piece } = event.detail;
  
  if (piece) {
    let info = `Clicked ${cell} - ${piece.color} ${piece.type}`;
    if (piece.rotation) info += `, rotation: ${piece.rotation}°`;
    if (piece.fairyName) info += `, fairy-name: ${piece.fairyName}`;
    if (piece.fairyCondition) info += `, fairy-condition: ${piece.fairyCondition}`;
    output.textContent = info;
  } else {
    output.textContent = `Clicked ${cell} - Empty square`;
  }
});

Keyboard Navigation

The chess board supports comprehensive keyboard navigation. Click on the board below and try these keys:

• Arrow keys: Navigate between squares
• Space: Select/move piece (see Piece Selection & Movement below)
• Delete: Remove piece from current square
• Escape: Clear board and cancel piece selection
• P/p, R/r, N/n, B/b, Q/q, K/k: Add white/black piece (uppercase=white, lowercase=black)
• E/e, T/t, A/a: Add fairy pieces (Empress, Amazon, Archbishop)
• Alt/Option+Left/Right: Rotate piece counter-clockwise/clockwise by 45°
• Alt/Option+Up/Down: Reset rotation to 0° / Set to 180°
• Shift+Up/Down: Flip board to white/black perspective

FEN / FFEN Live View

Every time the board position changes — via keyboard, mouse click, or programmatic API — the current position is recomputed and exposed through getFen(). The component accepts either a standard FEN string or a fairy-aware FFEN string through the same fen attribute, and it auto-detects the format so you do not need separate state or duplicate APIs.

FEN follows the standard Forsyth-Edwards Notation and is lossy: it keeps the board structure but drops specialized fairy metadata. FFEN extends the same format with fairy-aware metadata when needed, and the board preserves that information automatically when the input contains it.

Interact with the board below (add/delete/move pieces) and watch the string update in real time.

const board = document.getElementById('fen-sync-board');

// Called automatically after every board change
console.log(board.getFen());
// → "r1bqkb1r/pp3ppp/2np1n2/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R w - - 0 1 e4:gn:Chameleon"

// Monitor current square selection
const keyboardBoard = document.getElementById('keyboard-board');
const selectionOutput = document.getElementById('selection-output');

// Update display when selection changes
setInterval(() => {
  const current = keyboardBoard.getCurrentSquare();
  selectionOutput.textContent = current ? `Selected: ${current}` : 'No selection';
}, 100);

// Keyboard shortcuts available:
// Navigation:
// - Arrow keys: Navigate between squares
// - Click: Select square
//
// Piece management:
// - Delete: Remove piece from current square
// - Escape: Clear board
// - Shift+Escape: Reset to starting position
// - P/R/N/B/Q/K (uppercase): Add white pieces
// - p/r/n/b/q/k (lowercase): Add black pieces
// - E/T/A (uppercase/lowercase): Add fairy pieces
//
// Piece rotation:
// - Alt/Option+Left: Rotate counter-clockwise 45°
// - Alt/Option+Right: Rotate clockwise 45°
// - Alt/Option+Up: Reset rotation to 0°
// - Alt/Option+Down: Set rotation to 180°
//
// Board orientation:
// - Shift+Up: White perspective
// - Shift+Down: Black perspective

Piece Selection & Movement

Use Space or Enter to select and move pieces on the board:

• Space or Enter on occupied square: Toggle selection of the piece (selected pieces show with scale 1.1 and a blue glow)
• Space or Enter on empty square with piece selected: Move the selected piece to the empty square and clear selection
• Escape: Cancel piece selection
• Any other key: Automatically clears piece selection
• Board blur (click outside): Clears piece selection

💡 Tip: Try this workflow:

1. Navigate to a square with a piece (e.g., 'e4') using arrow keys
2. Press Space or Enter to select it (you'll see it scale up with a blue glow)
3. Navigate to an empty square using arrow keys
4. Press Space or Enter again to move the piece there

Piece Rotation and Fairy Notation

The chess-piece component supports rotation (0-315° in 45° steps) and fairy chess notation for problem compositions. Use the rotation attribute for piece rotation, fairy-name for top-left annotation (max 3 chars), and fairy-condition for bottom-right annotation.

Chess Pieces Component

The chess-piece component allows you to display individual chess pieces. Use the piece attribute for standard, fairy, or symbolic types (k, q, r, b, n, p, e, t, a, c, s, x, or a supported fairy-letter/number type) and the color attribute for white, black, or neutral pieces (w, b, n).

Board with Pieces Example

This example shows how to add pieces to the empty board programmatically.

// Example: Add pieces to create a starting position
document.addEventListener('DOMContentLoaded', () => {
  const board = document.getElementById('board-with-pieces');
  
  // Add white pieces
  addPiece(board, 'e1', 'k', 'w'); // White king
  addPiece(board, 'd1', 'q', 'w'); // White queen
  addPiece(board, 'a1', 'r', 'w'); // White rook
  addPiece(board, 'h1', 'r', 'w'); // White rook
  addPiece(board, 'c1', 'b', 'w'); // White bishop
  addPiece(board, 'f1', 'b', 'w'); // White bishop
  addPiece(board, 'b1', 'n', 'w'); // White knight
  addPiece(board, 'g1', 'n', 'w'); // White knight
  
  // Add white pawns
  for (let col = 0; col < 8; col++) {
    const file = String.fromCharCode(97 + col); // a-h
    addPiece(board, file + '2', 'p', 'w');
  }
  
  // Add black pieces
  addPiece(board, 'e8', 'k', 'b'); // Black king
  addPiece(board, 'd8', 'q', 'b'); // Black queen
  addPiece(board, 'a8', 'r', 'b'); // Black rook
  addPiece(board, 'h8', 'r', 'b'); // Black rook
  addPiece(board, 'c8', 'b', 'b'); // Black bishop
  addPiece(board, 'f8', 'b', 'b'); // Black bishop
  addPiece(board, 'b8', 'n', 'b'); // Black knight
  addPiece(board, 'g8', 'n', 'b'); // Black knight
  
  // Add black pawns
  for (let col = 0; col < 8; col++) {
    const file = String.fromCharCode(97 + col); // a-h
    addPiece(board, file + '7', 'p', 'b');
  }
});

function addPiece(boardElement, square, piece, color) {
  const squareElement = boardElement.shadowRoot.querySelector(`[data-coordinate="${square}"]`);
  if (squareElement) {
    const pieceElement = document.createElement('chess-piece');
    pieceElement.setAttribute('piece', piece);
    pieceElement.setAttribute('color', color);
    squareElement.appendChild(pieceElement);
  }
}

  

Board with Fairy Pieces Example

This example shows how to use extended FFEN.

FFEN String:

Data Coordinates

Each square has a data-coordinate attribute with standard chess notation (e.g., "e4", "a1"). You can select specific squares using CSS selectors or JavaScript:

// Select the e4 square
const e4Square = document.querySelector('chess-board').shadowRoot.querySelector('[data-coordinate="e4"]');

// Select all squares in the 4th rank
const fourthRank = document.querySelector('chess-board').shadowRoot.querySelectorAll('[data-coordinate$="4"]');

// Select all squares in the e-file
const eFile = document.querySelector('chess-board').shadowRoot.querySelectorAll('[data-coordinate^="e"]');
        

Compatible with html2canvas

to see the chess board as an image, you can use the html2canvas library to capture the current state of the chess board and render it as a canvas image. This is useful for saving or sharing the board position as an image.

// Example: Capture the chess board as an image using html2canvas
import html2canvas from 'html2canvas';
document.getElementById('snapshot').addEventListener('click', () => {
  const board = document.getElementById('board-with-f-pieces');
  const snapshotImage = document.getElementById('snapshot-image');

  // use html2canvas to capture the board as an image
  html2canvas(board).then(canvas => {
    snapshotImage.src = canvas.toDataURL();
  });
});
      

Try: Take Snapshot Save Snapshot