Skip to content

Seamless Integration Guide

Learn how to embed Neo Chess Board into your application and tailor it to your brand. This guide walks through the recommended setup for both vanilla JavaScript and React projects, then highlights the most useful customization hooks.

Prerequisites

  • An application that can serve static assets (Vite, Next.js, Create React App, etc.).
  • Node.js 18+.
  • Access to the @magicolala npm scope via GitHub Packages.

For installation basics, refer to the Quick Start section in the repository README.

1. Install and Configure the Registry

Create or update your .npmrc file so the @magicolala scope points to GitHub Packages:

@magicolala:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Replace ${GITHUB_TOKEN} with a personal access token that has the read:packages permission. Then install the library with your package manager of choice:

npm install @magicolala/neo-chess-board
# or
yarn add @magicolala/neo-chess-board
# or
pnpm add @magicolala/neo-chess-board

2. Render the Board

Vanilla JavaScript

import { NeoChessBoard } from '@magicolala/neo-chess-board';

const board = new NeoChessBoard(document.getElementById('board'), {
  theme: 'classic',
  interactive: true,
});

board.on('move', ({ from, to, fen }) => {
  console.log(`${from} → ${to}`);
});

<div id="board" style="width: 420px; height: 420px;"></div>

React

import { useState } from 'react';
import { NeoChessBoard } from '@magicolala/neo-chess-board/react';

export function Playground() {
  const [fen, setFen] = useState<string | undefined>();

  return (
    <NeoChessBoard
      fen={fen}
      theme="midnight"
      onMove={({ fen: nextFen }) => setFen(nextFen)}
      style={{ width: 440, height: 440, borderRadius: '1rem', overflow: 'hidden' }}
    />
  );
}

3. Customize the Look & Feel

Built-in Themes

Choose from the bundled presets through the theme option. Theme names correspond to those in the Themes catalog.

<NeoChessBoard theme="classic" />
<NeoChessBoard theme="midnight" />

Register a Custom Theme

import { registerTheme } from '@magicolala/neo-chess-board';

const auroraTheme = {
  light: '#f5f3ff',
  dark: '#1e1b4b',
  highlight: '#fbbf24',
  check: '#f59e0b',
  coordinates: '#312e81',
  // ...set the remaining palette fields here
};

registerTheme('aurora', auroraTheme);

new NeoChessBoard(container, { theme: 'aurora' });

Tip: Use the Theme Creator to generate the palette interactively and export ready-to-paste code.

Custom Piece Sets

import type { PieceSet } from '@magicolala/neo-chess-board';
import whiteKing from './pieces/wK.svg';
import blackKing from './pieces/bK.svg';

const glossyPieces: PieceSet = {
  defaultScale: 0.92,
  pieces: {
    K: { image: whiteKing },
    k: { image: blackKing },
    // provide other piece sprites as needed
  },
};

const board = new NeoChessBoard(container, {
  pieceSet: glossyPieces,
  background: '#0f172a',
});

Missing entries automatically fall back to the default minimalist sprites. Use offsetX, offsetY, or per-piece scale to nudge artwork into place.

4. Fine-tune Interactions

Highlighting & Coordinates

const board = new NeoChessBoard(container, {
  showCoordinates: true,
  highlightMoves: true,
  highlightLastMove: true,
  highlightCheck: true,
});

Event Lifecycle

Listen to board events (move, promotion, select, etc.) to synchronize with the rest of your application.

board.on('promotion', ({ square, setPiece }) => {
  openPromotionModal({
    square,
    onChoice(piece) {
      setPiece(piece);
    },
  });
});

In React, use the dedicated props: onMove, onPromotion, onSquareClick, and others.

Sound cues & board chrome

Runtime toggles delegate to the new audio and DOM managers, which means you can change ambience or styling without rebuilding the board.

board.setSoundEnabled(true);
board.setSoundUrls({
  white: '/sounds/light-move.mp3',
  black: '/sounds/dark-move.mp3',
});

// Apply inline CSS to the layered root element
board.setBoardStyle({
  borderRadius: '18px',
  boxShadow: '0 12px 35px rgba(15, 23, 42, 0.25)',
});

Changes propagate immediately—the board keeps a ResizeObserver active through BoardDomManager, and sound sources hot-reload via BoardAudioManager.

Translate squares into pixel coordinates

Use getRelativeCoords when you need to align your own overlays or DOM nodes with specific board squares. The helper understands files/ranks, orientation, and even non-square boards. It returns both the top-left origin and the center point for each queried square.

import { getRelativeCoords } from '@magicolala/neo-chess-board';

const { center } = getRelativeCoords(
  {
    boardWidth: 640,
    boardHeight: 640,
    files: 8,
    ranks: 8,
    orientation: 'white',
  },
  'e4',
);

// Position a tooltip over e4
tooltip.style.transform = `translate(${center.x}px, ${center.y}px)`;

You can also query multiple squares at once or work with rectangular boards by passing an array of algebraic identifiers:

const [from, to] = getRelativeCoords(
  {
    boardWidth: 960,
    boardHeight: 640,
    files: 8,
    ranks: 8,
    orientation: 'black',
  },
  ['g7', 'g2'],
);

drawArrow(from.center, to.center);

5. Layout and Responsiveness

Wrap the board in a responsive container and control its dimensions using CSS. Because the board uses a <canvas>, it scales smoothly with width/height changes.

<div className="board-shell">
  <NeoChessBoard theme="classic" autoFlip style={{ width: '100%', aspectRatio: '1 / 1' }} />
</div>

.board-shell {
  max-width: 520px;
  margin: 0 auto;
}

6. Persisting State

Combine PGN/FEN helpers with your own storage solution to keep games across sessions.

import { NeoChessBoard, parsePgn, toPgn } from '@magicolala/neo-chess-board';

const saved = localStorage.getItem('neo-chess-game');
const board = new NeoChessBoard(container, { fen: saved ?? undefined });

board.on('move', () => {
  localStorage.setItem('neo-chess-game', board.getFen());
});

7. Deploying

Neo Chess Board does not ship assets that require special hosting—once bundled by your build tool, it works on any static host or CDN. If you rely on external piece sprites, ensure they are copied by your bundler or reachable via public URLs.

With these building blocks you can integrate Neo Chess Board into landing pages, dashboards, or full-featured chess platforms with brand-consistent visuals and polished user flows.