<chess-board> web component

A chess board for your own pages, in one file with nothing to install. It draws a position from a FEN, plays through a game with the same move animation as the site's GIFs, and shows arrows and highlighted squares that change from move to move. Click the right half of the board below to go forward and the left half to go back.

<script src="https://rnbqkbnr.com/chess-board.js"></script>

<chess-board controls
  moves="1. e4 {[%cal Ge4d5,Ge4f5] The pawn takes space in the centre.} e5
    2. Nf3 {[%cal Rf3e5] Attacks the pawn on e5.} Nc6 {[%cal Gc6e5] Defends it.}
    3. Bc4 {[%cal Rc4f7] [%csl Rf7] Aims at f7, which only the king protects.} Bc5
    4. c3 {[%cal Gd2d4] Getting ready to play d4.} Nf6
    5. d4 exd4 6. cxd4 Bb4+"></chess-board>

Add the script once, anywhere on the page (link it as above, or download chess-board.js and serve your own copy). Then write <chess-board> elements wherever you want a board. It is free to use on any site.

Try it

Change the options and copy the HTML.

Attributes

Every attribute is optional; a bare <chess-board></chess-board> is the start position. Changing an attribute later (for example with setAttribute) updates the board, and a new fen or more moves slide the pieces to their new squares.

AttributeDefaultWhat it does
fenstart positionThe position, or the first position when there are moves. Just the board (8/8/4k3/8/8/4K3/4P3/8) or a full FEN with the side to move.
movesnoneThe moves to step through: 1. e4 e5 2. Nf3, e2e4 e7e5 g1f3, or a whole PGN. See Moves, comments, arrows.
ply0The position to open on, counted in single moves: 0 is the start, 3 is after White's second move, last is the end of the game. Negative numbers count from the end.
orientationwhiteblack shows the board from Black's side.
arrowsnoneArrows on the first position, each written as a from square and a to square: e2e4 g1f3. A letter in front picks the colour (R red, G green, B blue, Y yellow), or put any colour after a colon: Gg1f3 d2d4:purple.
squaresnoneHighlighted squares on the first position, with the same colours: e4 Gd5 f7:purple.
last-movesquaresHow the move just played is shown: squares tints the two squares, arrow draws an arrow, both does both, off shows nothing.
controlsoffAdds a bar under the board with first, back, play, forward, last and flip buttons, the name of the move, and its comment.
autoplayoffPlays the moves by itself while the board is on screen. Stops when the reader clicks the board or a button.
loopoffStarts again from the first position after the last move.
animationtraceHow a move is drawn. trace is the animation from the GIF maker: the piece's outline unwinds into a line, runs along the edges of the squares and winds up again on the new square. slide moves the piece straight there.
duration1000, or 300 for slideHow long a move takes, in milliseconds. 0 turns animation off.
delay1200The time between moves while playing, in milliseconds. A move is always given time to finish first.
clickonoff stops clicks and keys from changing the position (the buttons and the JavaScript methods still work).
dark, lightbrown, greyThe square colours. Any CSS colour: steelblue, #769656, rgb(150,100,75).
border9 black whiteThe border's width (a square is 45 wide), then its colour, then the colour of the letters and numbers. 0 removes the border and the coordinates.
bgnoneA picture under the squares: how strongly it shows (0 to 1), then its address. bg="0.3 /wood.jpg"
Moves, comments, arrows

Moves can be written the way they appear in books and PGN files (Nf3, exd5, O-O, e8=Q) or as a from square and a to square (g1f3, e7e8q). Move numbers, results, ! and ? marks and variations in round brackets are skipped, so a game copied from Lichess, Chess.com or a database can be pasted in as it is.

  • Named moves must be legal in the position. If one can't be read, the board keeps the moves before it and writes a warning to the browser console.
  • From-to moves are played as written without being checked, so they also work in positions that aren't legal chess (no kings, say).
  • If the FEN doesn't say who moves, White does, unless the moves start with 1...
  • A PGN's [FEN "..."] tag is used when there is no fen attribute.

Comments and arrows after a move

Text in curly brackets after a move is its comment, shown under the board when controls is on. Inside a comment, [%cal ...] draws arrows and [%csl ...] highlights squares while that move is on the board. This is the format Lichess and other tools write, so annotated studies keep their drawings. A comment before the first move belongs to the starting position.

<chess-board controls
  fen="r1bqkbnr/pppp1ppp/2n5/4p2Q/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 3 3"
  moves="{[%cal Rh5f7,Rc4f7] [%csl Rf7] White threatens mate on f7.}
    3... g6 {[%cal Gg6h5] Blocks the queen and attacks it.}
    4. Qf3 {[%cal Rf3f7,Rc4f7] The same threat again.}
    Nf6 {[%csl Gf6] The knight is in the way now.}"></chess-board>

Moves as the element's text

For a long game it can be easier to put the PGN between the tags instead of in an attribute. (If both are there, the attribute wins.)

[Event "A night at the opera"] [White "Paul Morphy"] [Black "Duke Karl / Count Isouard"] 1. e4 e5 2. Nf3 d6 3. d4 Bg4 4. dxe5 Bxf3 5. Qxf3 dxe5 6. Bc4 Nf6 7. Qb3 Qe7 8. Nc3 c6 9. Bg5 b5 10. Nxb5 cxb5 11. Bxb5+ Nbd7 12. O-O-O Rd8 13. Rxd7 Rxd7 14. Rd1 Qe6 15. Bxd7+ Nxd7 16. Qb8+ Nxb8 17. Rd8# 1-0
<chess-board controls ply="last">
  [Event "A night at the opera"]
  [White "Paul Morphy"]
  [Black "Duke Karl / Count Isouard"]

  1. e4 e5 2. Nf3 d6 3. d4 Bg4 4. dxe5 Bxf3 5. Qxf3 dxe5 6. Bc4 Nf6
  7. Qb3 Qe7 8. Nc3 c6 9. Bg5 b5 10. Nxb5 cxb5 11. Bxb5+ Nbd7
  12. O-O-O Rd8 13. Rxd7 Rxd7 14. Rd1 Qe6 15. Bxd7+ Nxd7
  16. Qb8+ Nxb8 17. Rd8# 1-0
</chess-board>
Stepping and playing

A board with moves can be stepped through without any buttons:

  • Click or tap the right half of the board for the next move, the left half for the one before.
  • Keys, once the board has focus (Tab to it or click it): → next, ← back, Home first position, End last position, Space play or pause.
  • controls adds the button bar, for readers who wouldn't guess that the board can be clicked.
  • autoplay plays the game as soon as the board scrolls into view, and loop keeps it going. A click or a key press hands control to the reader.

Stepping one move animates that move, including castling, en passant and promotion. Moves are drawn like the ones in the site's GIFs: the piece unwinds into a line that runs along the edges of the squares. A click while a move is still being drawn skips straight to the next one. Jumping further (to the start or the end, say) slides each piece to wherever it ends up. Readers who have asked their device for reduced motion get the moves without any animation.

<chess-board autoplay loop
  last-move="arrow" border="0"
  moves="e4 e5 Nf3 Nc6 Bb5 a6 Ba4 Nf6 O-O Be7 Re1 b5 Bb3 d6 c3 O-O"></chess-board>

For a quicker, plainer move, ask for a slide:

<chess-board controls animation="slide"
  moves="1. e4 c5 2. Nf3 d6 3. d4 cxd4 4. Nxd4 Nf6 5. Nc3 a6"></chess-board>
JavaScript

The element can be driven from a script, to build your own buttons, a move list, a lesson, or a board that follows a live game.

MethodWhat it does
next(), prev()One move forward or back.
first(), last()To the first or the last position.
goTo(ply)To any position (goTo(ply, false) skips the animation).
play(), pause()Start and stop playing the moves.
move(text)Plays a move from the position shown and returns true, or returns false if it can't be read. Any moves after the position shown are dropped. A second argument can carry what to show with it: move('Nf3', { arrows: 'Rf3e5', squares: 'e5', comment: 'Hits e5' }).
flip()Turns the board round.
PropertyWhat it holds
plyThe position shown (0 is the start). Setting it moves the board.
lengthThe number of moves.
positionThe position shown, as a full FEN.
historyThe moves, as a list of { san, uci, from, to, comment, fen }.
playingtrue while the moves are playing by themselves.
errorWhy the moves could not all be read, or an empty string.

The board sends a plychange event whenever the position shown changes. Its detail has ply, length, fen, and the move that led here: san, from, to and comment (empty strings at the start).

Your own move list

<chess-board id="board" moves="1. d4 d5 2. c4 e6 3. Nc3 Nf6 4. Bg5 Be7 5. e3 O-O 6. Nf3"></chess-board>
<div id="list"></div>

<script>
  customElements.whenDefined('chess-board').then(() => {
    const board = document.getElementById('board');
    const list = document.getElementById('list');
    function draw() {
      list.textContent = '';
      board.history.forEach((move, i) => {
        const el = document.createElement(i + 1 === board.ply ? 'b' : 'span');
        el.textContent = (i % 2 ? '' : i / 2 + 1 + '. ') + move.san + ' ';
        el.onclick = () => board.goTo(i + 1);
        list.append(el);
      });
    }
    board.addEventListener('plychange', draw);
    draw();
  });
</script>

A board that follows a game

move() adds moves as they happen. (Setting a longer moves attribute works too: a board showing the last move follows along.)

<chess-board id="live" last-move="both" click="off"></chess-board>
<button id="next">Play the next move</button>

<script>
  const live = document.getElementById('live');
  const incoming = ['e4', 'c5', 'Nf3', 'd6', 'd4', 'cxd4', 'Nxd4', 'Nf6', 'Nc3', 'a6'];
  document.getElementById('next').onclick = () => {
    live.move(incoming[live.ply]);   // slides the piece, marks the move
    console.log(live.position);      // the new FEN
  };
</script>
Size and styling

The board is as wide as the space it is given, like an image. Set its width with CSS, and its height follows:

chess-board { width: 320px; max-width: 100%; }

(Leave the height alone when controls is on, so the bar has room under the board.) Colours and the border come from the attributes. The parts inside can be styled from your own CSS:

SelectorWhat it styles
chess-board::part(board)The board drawing (rounded corners, shadows, and so on).
chess-board::part(controls)The button bar. It takes its font and text colour from the page.
chess-board::part(button)Each button in the bar.
chess-board::part(label)The move's name in the bar.
chess-board::part(caption)The comment under the bar.
--chess-board-focusA custom property: the colour of the keyboard focus outline.
<style>
  chess-board::part(board) {
    border-radius: 10px;
    box-shadow: 0 4px 14px rgb(0 0 0 / 0.35);
  }
  chess-board::part(controls) {
    background: #222; color: #eee;
    border-radius: 999px; padding: 2px 10px; margin-top: 8px;
  }
  chess-board::part(caption) { font-style: italic; text-align: center; }
</style>

<chess-board controls dark="#769656" light="#eeeed2" border="0" ply="2"
  moves="1. e4 {The king's pawn.} c5 {The Sicilian Defence.} 2. Nf3 d6 3. d4 cxd4 4. Nxd4"></chess-board>
More examples

A diagram with arrows and squares

<chess-board
  fen="r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R"
  arrows="f1b5 Gf1c4 Bd2d4"
  squares="Ye5 c6:purple"></chess-board>

A puzzle from Black's side

Black to move and mate in two. The board opens on the puzzle; clicking its right half plays the answer.

<chess-board orientation="black" last-move="arrow"
  fen="4r1k1/5ppp/8/4q3/8/8/5PPP/R5K1 b - - 0 1"
  moves="1... Qe1+ 2. Rxe1 Rxe1#"></chess-board>

Colours and borders

<chess-board></chess-board>
<chess-board dark="steelblue" light="lightgray" border="12 black white"></chess-board>
<chess-board dark="#769656" light="#eeeed2" border="0"></chess-board>
<chess-board dark="#b58863" light="#f0d9b5" border="6 #5c3317 #f0d9b5"></chess-board>
<chess-board dark="#555" light="#ddd" border="9 white black" orientation="black"></chess-board>

Changing the position from a script

With no moves at all, a new fen still animates: pieces that are in both positions slide, the others fade. (To get the traced move here, use move() or the moves attribute, so the board knows which piece went where.)

<chess-board id="board" fen="8/8/4k3/8/8/4K3/4P3/8"></chess-board>
<button data-fen="8/4k3/8/4K3/4P3/8/8/8">Opposition</button>

<script>
  document.querySelectorAll('button[data-fen]').forEach((button) => {
    button.onclick = () =>
      document.getElementById('board').setAttribute('fen', button.dataset.fen);
  });
</script>
Notes
  • Browsers: current Chrome, Edge, Firefox and Safari. The script must run for the board to appear, so add your own fallback (a board image, for instance) if that matters to you.
  • Screen readers: the board is announced as an image named after the move shown ("Chess board after 3. Bc4"). For a diagram that needs a fuller description, put your own role="img" and aria-label on the element.
  • What it isn't: a board to play on. Pieces can't be dragged, and the script only knows enough chess to read and name moves. For play against a bot, see handwritten chess.
  • Older pages: boards written for the first version (fen, arrows, dark, light, border, bg) look and work as before.
  • Just a picture? rnbqkbnr.com/<fen>.png gives a board image with no script at all.