chess_interface

This is a flutter package and doesn't support pure dart based project. For dart / backend project, checkout chess_interface_dart Package.

A customizable, feature-rich chess board widget built in Flutter. This package offers a robust foundation for integrating chess gameplay into your Flutter apps — complete with piece rendering, move validation, theming, and more.

Features

♟️ Full chess piece support with images
✅ Built-in move validation for all standard piece types
♻️ Customizable board themes and piece materials
🔄 Supports en passant, castling, and pawn promotion logic
📐 Interface-driven board interaction for flexible state management
🎨 Material Design color extensions for theming

Getting Started

Add the package to your pubspec.yaml:

dependencies:
  chess_interface:
    git:
      url: https://github.com/mryadavdilip/chess_interface.git

dependencies:
  chess_interface: ^1.2.1

Then import these:

import 'package:chess_board_widget/chess_board_widget.dart';
import 'package:chess_board_widget/logical_interface/interface.dart';
import 'package:chess_board_widget/models/BoardThemeConfig.dart';

Initialize ChessBoardProvider in your project

MultiProvider(
  providers: [
    ListenableProvider<ChessBoardProvider>(create: (_) => ChessBoardProvider()),
  ],
  child: Scaffold(
    body: ChessBoardWidget(),
  ),
);

Example

For a runnable Flutter example, see:

example/main.dart

Also refer to comments inside the example code.


import 'dart:math';
import 'package:chess_interface/arbiter/flutter_arbiter.dart';
import 'package:chess_interface/extensions/chess_piece.dart';
import 'package:chess_interface/extensions/color.dart';
import 'package:chess_interface/extensions/piece_color.dart';
import 'package:chess_interface/chess_interface_dart.dart';
import 'package:flutter/material.dart';
import 'package:chess_interface/models/board_theme_config.dart';

/// initialize game
Provider.of<ChessBoardProvider>(context, listen: false).init(
  ChessBoardInterface(
    fen: 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1',
    timeLimit: const Duration(minutes: 10),
  ),
);

/// use chess board widget
ChessBoardWidget(
  game: Provider.of<ChessBoardProvider>(context, listen: true).game,

  // optional
  onMove: (Position from, Position to) {},

  // optional
  playAs: PieceColor.black,

  // false by default
  rotateBoard: true,

  arbiter: FlutterArbiter(
    showDialogs: true,

    context: context,

    onGameOver: (gameOverBy) {
      // todo: handle gameOver
    },

    // optional
    onReachingPromotionRank: (position) async {
      // todo: show pieces to player to promote and must return whether player chose a piece or not, if returns false (i.e, player doesn't choose a piece), default promotion is made to queen.
      return true;
    },

    // callback when either player chose a piece or promoted to default (queen)
    onPromoted: (position, promotedTo) {},
  ),

  // true by default
  spectateInitially: false,

  boardSize: 300,

  config: BoardThemeConfig(
    boardColor: Colors.limeAccent,

    /// To add your own resources, refer to the assets folder structure inside this package. If your resources includes sparate materials for each color, add to path like this: "assets/your_materials_name/black/king.png" (or /white/ for white pieces). and same for all other pieces. If you've simple and fillable png recourses, simply add them in "assets/your_materials_name/bishop.png" path.
    materialVariety: materialsResources.keys.first,
  ),
),


/// call this to rebuild ChessBoardWidget, when some change is made to the [ChessBoardInterface]
Provider.of<ChessBoardProvider>(context, listen: false).notify();

Configuration

Theme Customization

Customize the board and pieces using BoardThemeConfig.

1) Use package assets (default)

You can define your own colors and piece styles via the asset directory:

BoardThemeConfig(
  boardColor: Colors.green[700],
  materialVariety: 'modern_minimalist',
);

2) Use your own (host app) assets (recommended)

If you want full control over visuals (remote images, SVGs, different folders, etc.), provide pieceImageProvider. When set, ChessBoardWidget will use it instead of building Image.asset(...) paths from materialVariety/directory/extension.

BoardThemeConfig(
  boardColor: Colors.green[700],
  pieceImageProvider: (type, color) {
    return AssetImage(
      'assets/my_chess_theme/${color.name}/${type.name}.png',
    );
  },
);

Piece Rendering

The ChessPiece class loads the appropriate asset based on the type, color, and selected material style when pieceImageProvider is not provided.

ChessPiece(type: PieceType.queen, color: PieceColor.black)
  .getResource('classic');

Move Validation

Use MoveValidator.isValidMove() to validate legal chess moves:

bool isValid = MoveValidator.isValidMove(ChessBoardInterface game, Position from, Position to);

It supports:

All standard chess moves
Pawn special rules
Castling logic (including history tracking)
En passant and double pawn pushes

FlutterArbiter (extends Arbiter)

FlutterArbiter to handle events like game over, time out and pawn promotion:

And more..

File Structure

chess_board_widget.dart – Main UI and logic
move_validator.dart – Move legality checker
piece.dart – Piece model and asset loader
arbiter.dart – Game over, timeOut, and promotion handler
board_theme_config.dart – Customization config
color_extension.dart – Color manipulation utilities
interface.dart – Board interaction interface
env.dart – Environment configuration for materials and colors

Assets

Ensure your pubspec.yaml declares your assets like so:

flutter:
  assets:
    - assets/classic/pawn.png
    - assets/wooden/king.png

Contributing

Contributions are welcome! Please open issues and pull requests to help improve this Package.

License

MIT License. See LICENSE for details.