# vue3-chessboard

> vue3-chessboard is a component library for creating chess web apps with vue3

Latest version **1.3.4** (published 2026-10-03) · GPL-3.0 license · 0 weekly downloads

## Install

```sh
npm install vue3-chessboard
pnpm add vue3-chessboard
yarn add vue3-chessboard
bun add vue3-chessboard
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.3.4 |
| Published | 2026-10-03 |
| First published | 2022-10-03 |
| Weekly downloads | 0 |
| License | GPL-3.0 |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 290.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 88 |
| Author | Luca Hendrik Helms |
| Maintainers | lucahendrik |
| Keywords | vue, chessboard, chess, vue3, lichess, chessground, chess.js, typescript |

## Links

- npm: https://www.npmjs.com/package/vue3-chessboard
- Repository: https://github.com/qwerty084/vue3-chessboard
- Homepage: https://qwerty084.github.io/vue3-chessboard-docs/
- Issues: https://github.com/qwerty084/vue3-chessboard/issues
- npm.io page: https://npm.io/package/vue3-chessboard

## Dependencies (2)

- [chess.js](https://npm.io/package/chess.js.md) ^1.0.0-beta.6
- [chessground](https://npm.io/package/chessground.md) ^9.0.2

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.3.4 (latest) — 2026-10-03
- 1.2.0-alpha.1 (alpha) — 2023-06-18
- 1.3.3 — 2024-03-02
- 1.3.2 — 2023-12-10
- 1.3.1 — 2023-12-10
- 1.3.0 — 2023-12-10
- 1.2.4 — 2023-10-16
- 1.2.3 — 2023-09-08
- 1.2.2 — 2023-08-27
- 1.2.1 — 2023-08-02
- 1.2.0 — 2023-07-03
- 1.2.0-beta.1 — 2023-07-01
- 1.2.0-beta.0 — 2023-06-26
- 1.1.8 — 2023-06-04
- 1.1.7 — 2023-05-20
- … 19 more at https://npm.io/package/vue3-chessboard/versions

## README

# vue3-chessboard

[![Unit Tests](https://github.com/qwerty084/vue3-chessboard/actions/workflows/tests.yml/badge.svg)](https://github.com/qwerty084/vue3-chessboard/actions/workflows/tests.yml)
[![CodeQL](https://github.com/qwerty084/vue3-chessboard/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/qwerty084/vue3-chessboard/actions/workflows/codeql.yml)
[![npm](https://img.shields.io/npm/v/vue3-chessboard)](https://www.npmjs.com/package/vue3-chessboard)

vue3-chesssboard is a component library for vue 3 built with [lichess chessground](https://github.com/lichess-org/chessground) & [chess.js](https://github.com/jhlywa/chess.js).

![Chessboard](https://media3.giphy.com/media/cWw6eHQ7AmjDXbWm6w/giphy.gif?cid=790b7611cce1bb251c4ae6a786ea4dc8be97b1563f59d989&rid=giphy.gif&ct=g)

You can find a demo and the full library documentation [here](https://qwerty084.github.io/vue3-chessboard-docs/).

## Table of contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Docs](#docs)

# Features:

- Customizable chessboard
- Custom Events for check, checkmate, draw, move etc.
- Undo Moves, reset game, get opening name, get current fen...
- Promotion dialog window
- Fully typed API/Custom Events

# Installation

```
npm i vue3-chessboard
```

# Usage

Basic Example (Composition API)

```html
<script setup>
import { TheChessboard } from 'vue3-chessboard';
import 'vue3-chessboard/style.css';
</script>

<template>
  <TheChessboard />
</template>
```

Basic Example (Options API)

```html
<template>
  <TheChessboard />
</template>

<script>
import { TheChessboard } from 'vue3-chessboard';
import 'vue3-chessboard/style.css';

export default {
  components: {
    TheChessboard,
  },
};
</script>
```

<hr>

Example Typescript Component

```html
<script setup lang="ts">
import { TheChessboard } from 'vue3-chessboard';
import 'vue3-chessboard/style.css';
import type { BoardApi, BoardConfig } from 'vue3-chessboard';

let boardAPI: BoardApi;
const boardConfig: BoardConfig = {
  coordinates: true,
};

function handleCheckmate(isMated: string) {
  if (isMated === 'w') {
    alert('Black wins!');
  } else {
    alert('White wins!');
  }
}
</script>

<template>
  <section>
    <div>
      <button @click="boardAPI?.toggleOrientation()">
        Toggle orientation
      </button>
      <button @click="boardAPI?.resetBoard()">Reset</button>
      <button @click="boardAPI?.undoLastMove()">Undo</button>
      <button @click="boardAPI?.toggleMoves()">Threats</button>
    </div>
    <TheChessboard
      :board-config="boardConfig"
      @board-created="(api) => (boardAPI = api)"
      @checkmate="handleCheckmate"
    />
  </section>
</template>
```

Example Javascript Component

```html
<script setup>
import { TheChessboard } from 'vue3-chessboard';
import 'vue3-chessboard/style.css';

let boardAPI;
const boardConfig = {
  coordinates: true,
};

function handleCheckmate(isMated) {
  if (isMated === 'w') {
    alert('Black wins!');
  } else {
    alert('White wins!');
  }
}
</script>

<template>
  <section>
    <div>
      <button @click="boardAPI?.toggleOrientation()">
        Toggle orientation
      </button>
      <button @click="boardAPI?.resetBoard()">Reset</button>
      <button @click="boardAPI?.undoLastMove()">Undo</button>
      <button @click="boardAPI?.toggleMoves()">Threats</button>
    </div>
    <TheChessboard
      :board-config="boardConfig"
      @board-created="(api) => (boardAPI = api)"
      @checkmate="handleCheckmate"
    />
  </section>
</template>
```

# Docs
You can find the full documentation [here](https://qwerty084.github.io/vue3-chessboard-docs/).

## Setup:

- Just install the package and import the component in your project, like shown above.
- Don't forget to include the stylesheet: <br>
  `import 'vue3-chessboard/style.css';`

### Chessboard config

You can pass a config object to the chessboard component to modify the board to your needs, as a prop (:board-config). The config object is optional and will be merged with the [default config](https://github.com/qwerty084/vue3-chessboard/blob/main/src/helper/DefaultConfig.ts).
The default config is based on the [lichess board config](https://github.com/lichess-org/chessground/blob/master/src/state.ts).
Additionally custom callback functions can be passed to the component.
For example a custom function can be run on piece selection or after each move.

### API

The chessboard component provides an API to interact with the chessboard. The API is accessible via the board-created event. The event will be emitted when the chessboard is created and ready to use.

### Available methods:

For a full list of available methods please visit the [documentation](https://qwerty084.github.io/vue3-chessboard-docs/board-api.html).

### Custom Events

You can listen for events on the chessboard component. The following events are available:

- boardCreated - Emitted when the chessboard is created and the API is ready to use
- checkmate - Emitted when a player is checkmated
- stalemate - Emitted when a player is stalemated
- draw - Emitted when the game is drawn
- check - Emitted when a player is checked
- promotion - Emitted when a player promotes
- move - Emitted when a player makes a move

```ts
const emit = defineEmits<{
  (e: 'boardCreated', boardApi: BoardApi): void;
  (e: 'checkmate', isMated: PieceColor): void;
  (e: 'stalemate'): void;
  (e: 'draw'): void;
  (e: 'check', isInCheck: PieceColor): void;
  (e: 'promotion', promotion: PromotionEvent): void;
  (e: 'move', move: MoveEvent): void;
}>();
```

---
_Source: https://npm.io/package/vue3-chessboard · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._