https://github.com/lichess-org/pgn-viewer
PGN viewer widget
https://github.com/lichess-org/pgn-viewer
chess javascript lichess pgn typescript viewer
Last synced: 8 months ago
JSON representation
PGN viewer widget
- Host: GitHub
- URL: https://github.com/lichess-org/pgn-viewer
- Owner: lichess-org
- License: gpl-3.0
- Created: 2022-07-18T08:23:26.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2025-05-06T19:40:49.000Z (about 1 year ago)
- Last Synced: 2025-05-12T20:15:31.724Z (about 1 year ago)
- Topics: chess, javascript, lichess, pgn, typescript, viewer
- Language: TypeScript
- Homepage: https://lichess.org
- Size: 834 KB
- Stars: 120
- Watchers: 8
- Forks: 29
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Lichess PGN Viewer
[](https://github.com/lichess-org/pgn-viewer/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@lichess-org/pgn-viewer)
PGN viewer widget, designed to be embedded in content pages.
This won't replace a fully featured [analysis board](https://lichess.org/analysis).
## See it in action
- [In a forum post](https://lichess.org/forum/game-analysis/strong-fm-showed-me-a-line-which-i-could-use-one-year-later-against-himself-)
- [In an opening page](https://lichess.org/opening/Caro-Kann_Defense_Advance_Variation)
- [In a user blog post](https://lichess.org/@/mfeeney88/blog/analysis-paralysis/NmISTSVM)
- [As a full-screen game embed](https://lichess.org/embed/game/ErSfVbRk)
## License
Lichess PGN Viewer is distributed under the **GPL-3.0 license** (or any later version, at your option).
When you use it for your website, your combined work may be distributed only under the GPL.
**You must release your source code** to the users of your website.
Please read more about GPL for JavaScript on [greendrake.info](https://greendrake.info/publications/js-gpl).
## Goals
- load and render very fast
- browse through a game
- variation tree
- PGN comments
- players and clocks
- mobile support
- accessible to screen readers with ARIA support
- translatable and customisable
- client-side only
- easy to set up on any page
### Non Goals
- custom user moves
- engine support
- opening explorer
For these features, use an [analysis board](https://lichess.org/analysis) or [Lichess studies](https://lichess.org/study).
## Accessibility
The viewer is fully accessible to screen reader users with:
- **Complete board representation**: Screen readers can navigate through all 64 squares with piece positions announced
- **Live move announcements**: Real-time narration of moves including number, color, notation, and annotations
- **Keyboard navigation**: All controls accessible via keyboard (arrow keys for moves, 'f' to flip board)
- **ARIA labels and roles**: Comprehensive semantic markup for assistive technologies
- **Game context**: Players, ratings, result, and timing information properly announced
## Build and run
```
pnpm install
pnpm run demo
```
Then open the demo page at http://localhost:8080
## Installation
### As an NPM package
```
npm i @lichess-org/pgn-viewer
```
## Usage
```js
import LichessPgnViewer from '@lichess-org/pgn-viewer';
const lpv = LichessPgnViewer(domElement, {
pgn: 'e4 c5 Nf3 d6 e5 Nc6 exd6 Qxd6 Nc3 Nf6',
});
// lpv is an instance of PgnViewer , providing some utilities such as:
lpv.goTo('first');
lpv.goTo('next');
lpv.flip();
console.log(lpv.game);
// see more in pgnViewer.ts
```
### Configuration
```js
const lpv = LichessPgnViewer(domElement, {
pgn: 'e4 c5 Nf3 d6 e5 Nc6 exd6 Qxd6 Nc3 Nf6',
// ... more Config
});
```
See [all configuration options in the documented source code](https://github.com/lichess-org/pgn-viewer/blob/master/src/config.ts#L3).
View more examples in `demo/index.html`
## Styles
### SCSS (recommended)
If you use [SCSS](https://sass-lang.com/), you can import the styles with:
```scss
@import '../../node_modules/@lichess-org/pgn-viewer/scss/lichess-pgn-viewer.lib';
```
Customisable SCSS variables are [available](https://github.com/lichess-org/pgn-viewer/blob/master/scss/_lichess-pgn-viewer.lib.scss), see [how lichess configures pgn-viewer with SCSS](https://github.com/lichess-org/lila/blob/master/ui/common/css/component/_lichess-pgn-viewer.scss).
### CSS
Alternatively you can build a CSS file with
```sh
npm run sass-prod
```
Then copy the `dist/lichess-pgn-viewer.css` file into your project.
## Testing
```bash
pnpm test
## or
pnpm test:watch
```
## Wrappers
- Vue.js: [dragunovartem99/vue-pgn-viewer](https://github.com/dragunovartem99/vue-pgn-viewer)
More? Please make a pull request to include it here.
## Release procedure
- https://github.com/lichess-org/pgn-viewer/actions/workflows/release.yaml
- [Run workflow]
- Branch: master
- Version tag: vX.Y.Z
The release workflow will increment the package.json version, create the tag, the github release, and publish to npm