react-native-chess-board-editor

A highly flexible and customizable React Native library for creating and editing chess board positions (FEN strings) without enforcing game rules. Perfect for building puzzle creators, position analysis tools, or chess setup utilities.

📚 Full Documentation |

✨ Features

• 🎯 Intuitive Drag & Drop - Smooth, native gesture handling powered by Reanimated 3
• 🎨 Fully Customizable - Control colors, sizes, styles, and layouts
• ♟️ Multiple Piece Sets - Includes alpha, cburnett, and merida piece sets, plus support for custom sets
• 🔧 Granular Components - Use individual components or the unified BoardEditor
• 🎭 No Chess Rules - Create any position, legal or illegal
• 📋 FEN Support - Full FEN string editing and manipulation
• ⚡ TypeScript - Complete type definitions included
• 🧪 Well Tested - Comprehensive test coverage

📦 Installation

npm install react-native-chess-board-editor

or

yarn add react-native-chess-board-editor

Peer Dependencies

This library requires the following peer dependencies:

npm install react-native-gesture-handler react-native-reanimated react-native-svg

Make sure to complete the setup for react-native-gesture-handler and react-native-reanimated.

🚀 Quick Start

Basic Usage

import React, { useState } from 'react';
import { View } from 'react-native';
import { BoardEditor } from 'react-native-chess-board-editor';

export default function App() {
  const [fen, setFen] = useState('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1');

  return (
    <View style={{ flex: 1, padding: 20 }}>
      <BoardEditor
        initialFen={fen}
        onFenChange={setFen}
      />
    </View>
  );
}

Using Individual Components

import React, { useState } from 'react';
import { View } from 'react-native';
import {
  EditableBoard,
  PieceBank,
  FenDisplay,
  TurnToggler,
  CastlingRightsTogglers,
} from 'react-native-chess-board-editor';

export default function CustomEditor() {
  const [fen, setFen] = useState('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1');

  return (
    <View>
      <EditableBoard fen={fen} onFenChange={setFen} />
      <PieceBank />
      <FenDisplay fen={fen} onFenChange={setFen} editable />
      <TurnToggler turn="w" onTurnChange={(turn) => {/* handle */}} />
      <CastlingRightsTogglers castlingRights="KQkq" onCastlingChange={(rights) => {/* handle */}} />
    </View>
  );
}

🧩 Components

Core Components

| Component | Description | |-----------|-------------| | BoardEditor | All-in-one component combining board, bank, and controls | | EditableBoard | Interactive chess board with drag & drop | | PieceBank | Piece palette for adding pieces to the board | | FenDisplay | Display and edit FEN strings |

Control Components

| Component | Description | |-----------|-------------| | TurnToggler | Switch between white and black to move | | CastlingRightsTogglers | Toggle castling availability (K, Q, k, q) | | EnPassantInput | Set en passant target square | | EditorToolsPanel | Collection of editor utility buttons | | PieceSetSelector | Switch between different piece set styles | | FlipBoardButton | Rotate the board 180° |

Utility Components

| Component | Description | |-----------|-------------| | Piece | Render individual chess pieces | | RankLabels | Display rank labels (1-8) | | FileLabels | Display file labels (a-h) |

🎨 Customization

Theming

Use the BoardThemeProvider to customize board appearance:

import { BoardThemeProvider } from 'react-native-chess-board-editor';

<BoardThemeProvider
  theme={{
    lightSquareColor: '#F0D9B5',
    darkSquareColor: '#B58863',
    squareSize: 45,
  }}
>
  <BoardEditor initialFen={fen} onFenChange={setFen} />
</BoardThemeProvider>

Custom Piece Sets

Register and use custom piece renderers:

import { registerCustomPieceSet, BoardEditor } from 'react-native-chess-board-editor';

registerCustomPieceSet('myCustomSet', {
  K: (props) => <MyWhiteKing {...props} />,
  Q: (props) => <MyWhiteQueen {...props} />,
  // ... other pieces
});

<BoardEditor pieceSet="myCustomSet" />

Styling Props

All components accept standard React Native style props:

<EditableBoard
  squareSize={50}
  lightSquareColor="#ECECEC"
  darkSquareColor="#769656"
  style={{ borderRadius: 8 }}
/>

UI Configuration

The BoardEditor component accepts a nested uiConfig prop that allows you to configure all aspects of the editor UI:

<BoardEditor
  initialFen={fen}
  onFenChange={setFen}
  uiConfig={{
    // Board orientation
    flipped: false,

    // Piece bank configuration
    pieceBank: {
      show: true,
      layout: 'horizontal',
      pieceSize: 40,
      showLabel: true,
      labelConfig: {
        fontSize: 14,
        color: '#333',
        fontWeight: '600',
      },
      bankStyle: { backgroundColor: '#f5f5f5' },
      pieceStyle: { margin: 4 },
    },

    // Board configuration
    editableBoard: {
      coordinateLabels: {
        show: true,
        fontSize: 12,
        color: '#666',
      },
      boardStyle: { borderRadius: 4 },
      pieceStyle: { opacity: 1 },
    },

    // FEN display configuration
    fenDisplay: {
      show: true,
      editable: true,
      inputStyle: { fontSize: 14 },
      containerStyle: { padding: 8 },
    },

    // Editor tools panel configuration
    editorToolsPanel: {
      show: true,
      title: 'Editor Tools',
      initialExpanded: false,
      showTurnToggler: true,
      showCastlingRights: true,
      showEnPassantInput: true,
      showPieceSetSelector: true,
      containerStyle: { borderRadius: 8 },
    },

    // Flip board button configuration
    flipBoardButton: {
      show: true,
      location: 'overlay',
      variant: 'overlay',
      buttonStyle: { backgroundColor: '#007AFF' },
    },
  }}
/>

All nested configuration properties are optional and have sensible defaults. The nested structure provides full TypeScript IntelliSense support for easy discovery of available options.

Migrating from v0.1.0? See MIGRATION.md for a complete migration guide.

📖 API Documentation

For detailed API documentation, prop references, and advanced usage examples, visit:

📚 https://your-docs-site.com

🔧 Advanced Features

FEN Utilities

The library exports utility functions for FEN manipulation:

import { parseFen, updateFenField, validateFen } from 'react-native-chess-board-editor';

const fenParts = parseFen('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1');
const newFen = updateFenField(fen, 'turn', 'b');
const isValid = validateFen(fen);

Custom Piece Filtering

Filter pieces shown in the PieceBank:

import { PieceBank, whitePiecesOnly } from 'react-native-chess-board-editor';

<PieceBank pieceFilter={whitePiecesOnly} />

Board Flipping

The board can be flipped to show from black's perspective:

<EditableBoard fen={fen} onFenChange={setFen} flipped />

📋 Requirements

• React Native >= 0.64
• react-native-gesture-handler >= 2.0.0
• react-native-reanimated >= 3.0.0
• react-native-svg >= 13.0.0

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Documentation
• npm Package
• GitHub Repository
• Issue Tracker

🙏 Acknowledgments

• Piece sets from lichess.org
• Built with react-native-builder-bob

Made with ❤️ for the React Native community