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

Feature	Details
Rendering	QFC4 fonts with tajweed coloring, 5 themes, auto night mode
Audio	22 reciters, 3 quality levels, offline download, speed/repeat
Tafsir	14 tafsir books with download & cache
Text	40+ translation editions, embedded Uthmani + Simple Arabic
Word-by-word	Morphology data + word audio
Search	Arabic-aware with diacritic normalization, voice search
Reading	Daily wird goals, streaks, weekly/monthly stats
Widgets	35 composable widgets + 6 ready-made screens

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

Import	Contents
quran_kit/headless.dart	All services, zero widgets
quran_kit/core.dart	Metadata, models, storage, themes
quran_kit/rendering.dart	Font download, cache, load, render
quran_kit/rendering_ui.dart	Page widgets + hifz + sajda + zoom + dual
quran_kit/audio.dart	Audio service
quran_kit/audio_ui.dart	Audio bar + reciter picker + download
quran_kit/tafsir.dart	Tafsir service
quran_kit/tafsir_ui.dart	Tafsir sheet + picker
quran_kit/text.dart	Text/translation service
quran_kit/text_ui.dart	Edition picker
quran_kit/search.dart	Search engine + voice
quran_kit/search_ui.dart	Search bar + voice widget
quran_kit/word.dart	Word-by-word service
quran_kit/word_ui.dart	Word info sheet
quran_kit/content.dart	Asbab al-nuzul + khatma du'a
quran_kit/content_ui.dart	Asbab nuzul sheet
quran_kit/reading.dart	Wird tracker + stats + settings
quran_kit/reading_ui.dart	Tracker + stats + qiraa picker
quran_kit/navigation_ui.dart	Bookmarks, juz, surah index, theme picker, share
quran_kit/theme.dart	Auto night mode
quran_kit/theme_ui.dart	Night mode widget
quran_kit/kit.dart	QuranKitConfig + QuranKit + controller
quran_kit/screens.dart	6 ready-made screens

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

Screen	Purpose
QuranReaderScreen	Full reader with page view, audio bar, navigation
QuranSearchScreen	Full-text search with filters
QuranSettingsScreen	Theme, reciter, translation, tafsir, font size
AyahDetailsScreen	Ayah text + translation + tafsir + word-by-word
QuranBookmarksScreen	Bookmark list with swipe-to-delete
QuranDownloadsScreen	Audio + text download management

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

Data	Source	Caching
Audio (22 reciters)	everyayah.com	Per-surah MP3 files
Translations (40+)	api.alquran.cloud	Per-edition JSON
Tafsir (14 books)	GitHub Releases CDN	Per-book JSON
Word-by-word	GitHub Releases CDN	Per-surah JSON
Asbab al-nuzul	GitHub Releases CDN	Single JSON
Word audio	audio.qurancdn.com	Streamed
QFC4 fonts	Configurable CDN	5-page ZIP bundles
Arabic text	Embedded assets	In-memory (gzipped)

Platform Support

Platform	Status
Android	✅ Supported
iOS	✅ Supported
Web	❌ Not supported (dart:io dependency)
Desktop	⚠️ Untested

Requirements

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

License

MIT — see LICENSE.