islam_flutter 0.0.3

A comprehensive Flutter package for Islamic applications.

islam_flutter

Flutter package for accessing Quran text, translations, and tafseer. Heavily inspired by islam.js.

Features

• All 114 chapters with metadata (name, transliteration, type, verse count)
• Verses in Hafs and Warsh dialects
• 10 translations (English, French, Urdu, Indonesian, Russian, Turkish, Bengali, Chinese, Spanish, Swedish)
• 8 tafseer editions (Al-Jalalayn, Ibn Kathir, Al-Qurtubi, Al-Tabari, Al-Saddi, Qushairi, Ibn Kathir Urdu, Fathul Majid)
• One-time database download with progress callback
• Fully offline after first run
• SHA-256 integrity check on the downloaded database

Installation

dependencies:
  islam_flutter: ^0.0.1

Setup

Call QuranService.init() once at app startup before using the service. This checks whether the database is cached locally and downloads it if not.

await QuranService().init(
  onDownloadStart: () {
    // show progress UI
  },
  onProgress: (double progress) {
    // progress is 0.0–1.0
  },
);

The database is downloaded only on the first launch (or when the package ships a new DB version).

Usage

final quran = QuranService();

// All chapters
final chapters = await quran.getAllChapters();

// Single chapter
final fatiha = await quran.getChapterById(1);

// Verses (Hafs dialect by default)
final verses = await quran.getVersesByChapter(1);

// Verses in Warsh dialect
final warsh = await quran.getVersesByChapter(1, dialect: DialectEnum.warsh);

// Single verse
final verse = await quran.getVerse(2, 255);

// Verse with translation
final translated = await quran.getVersesWithTranslation(
  [(chapterId: 2, verseId: 255)],
  translation: TranslationEnum.french,
);

// Verse with translation and tafseer
final detailed = await quran.getVerseWithTafseer(
  1,
  1,
  translation: TranslationEnum.english,
  tafseer: TafseerEnum.ibnKathir,
);

Enums

TranslationEnum

Value	Language
english	English — Saheeh International
french	French — Muhammad Hamidullah
urdu	Urdu — Abul A'ala Maududi
indonesian	Indonesian — Ministry of Religious Affairs
russian	Russian — Elmir Kuliev
turkish	Turkish — Diyanet Isleri
bengali	Bengali — Muhiuddin Khan
chinese	Chinese — Ma Jian
spanish	Spanish — Muhammad Isa Garcia
swedish	Swedish — Knut Bernström

TafseerEnum

Value	Name	Language
jalalayn	Tafsir Al-Jalalayn	English
ibnKathir	Tafsir Ibn Kathir (abridged)	English
qushayri	Al-Qushairi Tafsir	English
tabari	تفسير الطبري	Arabic
qurtubi	تفسير القرطبي	Arabic
saddi	تفسير السعدي	Arabic
ibnKathirUrdu	تفسیر ابن کثیر	Urdu
fathulMajid	تاফসীর ফাতহুল মাজিদ	Bengali

DialectEnum

Value	Description
hafs	Hafs an Asim (default)
warsh	Warsh an Nafi

Error handling

All methods throw typed exceptions from the package:

• IslamFlutterDatabaseException - database open or query failure
• NotFoundException - chapter or verse not found
• InvalidArgumentException - chapter/verse ID out of valid range

Platform support

Android	iOS	Web	macOS	Windows	Linux
✅	✅	—	✅	—	—

Requirements

• Flutter 3.x or later
• Dart 3.x or later
• Internet connection on first launch for database download