quran_kit #

A complete, modular Quran toolkit for Flutter — rendering, audio, tafsir, search, word-by-word, reading tracker, and 35+ ready-made UI widgets. Import only what you need.

Features #

Architecture #

Three import tiers — use only what you need:

┌─────────────────────────────────────┐
│  screens.dart  — 6 ready-made screens│
├─────────────────────────────────────┤
│  *_ui.dart     — widgets per domain  │
├─────────────────────────────────────┤
│  headless.dart — services only       │
└─────────────────────────────────────┘

Quick Start #

1. Install #

dependencies:
  quran_kit: ^0.1.0

2. Initialize #

import 'package:quran_kit/kit.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await QuranKit.initialize(QuranKitConfig(
    fontBaseUrl: 'https://github.com/user/repo/releases/download/v1.0.0',
  ));

  runApp(const MyApp());
}

3. Use a ready-made screen #

import 'package:quran_kit/kit.dart';
import 'package:quran_kit/screens.dart';

class QuranPage extends StatefulWidget {
  const QuranPage({super.key});

  @override
  State<QuranPage> createState() => _QuranPageState();
}

class _QuranPageState extends State<QuranPage> {
  final _controller = QuranReaderController();

  @override
  void initState() {
    super.initState();
    _controller.init();
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return QuranReaderScreen(
      controller: _controller,
      enableZoom: true,
      onAyahTap: (surah, ayah) {
        Navigator.push(context, MaterialPageRoute(
          builder: (_) => AyahDetailsScreen(surah: surah, ayah: ayah),
        ));
      },
    );
  }
}

4. Or compose your own UI #

import 'package:quran_kit/rendering_ui.dart';
import 'package:quran_kit/audio_ui.dart';
import 'package:quran_kit/navigation_ui.dart';

// Use individual widgets:
QuranPageView(initialPage: 1, onPageChanged: (p) => ...)
QuranAudioPlayerBar(state: audioState, onPlayPause: () => ...)
QuranBottomInfoBar(theme: theme, currentPage: page, ...)

Import Guide #

Configuration #

QuranKitConfig(
  fontBaseUrl: 'https://...',         // Required: CDN for QFC4 fonts
  enableAudio: true,                  // Audio playback service
  enableTafsir: true,                 // Tafsir (exegesis) service
  enableSearch: true,                 // Full-text search
  enableWordByWord: true,             // Word-by-word data
  enableAsbabNuzul: true,             // Occasions of revelation
  defaultReciterIndex: 0,             // Mishary Alafasy
  defaultTafsirId: 'al-tabari',       // Default tafsir book
  defaultEditionId: 'ar-uthmani',     // Default text edition
  defaultQiraa: 'hafs',              // Default qira'a
  defaultTheme: QuranThemes.parchment,// Reading theme
  readingGoal: 20,                    // Daily pages goal
  showTajweed: true,                  // Tajweed coloring
  enableAutoNightMode: false,         // Time-based dark mode
  nightStartHour: 18,                // Night start (6 PM)
  nightEndHour: 6,                   // Night end (6 AM)
  storage: null,                      // Custom QuranStorage (default: JSON file)
)

Ready-Made Screens #

All screens support builder callbacks for customization:

QuranReaderScreen(
  controller: controller,
  appBarBuilder: (context, info) => AppBar(title: Text(info.surahName)),
  bottomBarBuilder: (context, info) => MyBottomBar(info: info),
  audioBarBuilder: (context, state) => MyAudioBar(state: state),
  drawerBuilder: (context, info) => MyDrawer(),
);

Themes #

5 built-in themes:

QuranThemes.emeraldNight  // Dark green
QuranThemes.parchment     // Classic beige
QuranThemes.midnight      // Dark blue
QuranThemes.amoledDark    // Pure black AMOLED
QuranThemes.daylight      // Clean white

Or define your own:

QuranReadingTheme(
  id: 'custom',
  name: 'Custom Theme',
  backgroundColor: Color(0xFFF5F5F5),
  textColor: Color(0xFF333333),
  accentColor: Color(0xFF1E88E5),
  highlightColor: Color(0x331E88E5),
  isDark: false,
)

Custom Storage #

Implement QuranStorage to use your own persistence layer:

class HiveQuranStorage implements QuranStorage {
  @override
  Future<String?> getString(String key) async => box.get(key);

  @override
  Future<void> setString(String key, String value) async => box.put(key, value);

  // ... implement all methods
}

await QuranKit.initialize(QuranKitConfig(
  fontBaseUrl: '...',
  storage: HiveQuranStorage(),
));

Data Sources #

Platform Support #

Requirements #

• Dart SDK ^3.7.1
• Flutter >=3.0.0
• Network access on first run (font + data downloads)

License #

MIT — see LICENSE.