qcf_quran

English | العربية

Quran page view Search and verse

High-fidelity Quran Mushaf rendering in Flutter using the QCF (Quranic Computer Font) set. This package bundles per-page QCF fonts and utilities so you can:

  • Display a full mushaf with right-to-left paging.
  • Render any single ayah with the correct per-page ligatures and verse end symbol.
  • Query metadata like page numbers, surah/juz names, verse counts, and search the Arabic text.

The package includes the QCF font families and a compact API to build Quran apps quickly.

Note: This package bundles 604 per-page QCF font files. The package size is large because of these embedded fonts.

Features

  • Page-accurate mushaf using internal QCF fonts (604 pages)
  • PageviewQuran: horizontally swipeable pages (RTL), per-page fonts applied automatically
  • QcfVerse: render a single ayah with the correct font and verse number glyph
  • Utilities and data:
    • getPageNumber, getPageData, getSurahName(…)/Arabic/English, getVerse(…)/QCF, getJuzNumber(…)
    • searchWords(…) for simple Arabic text search (up to 50 results)
    • Normalization helpers normalise(…) and removeDiacritics(…)
  • Example app showcasing page view, single verse, search, and page jump

Getting started

  1. Add the dependency to your pubspec.yaml:
dependencies:
  qcf_quran: ^0.0.2
  1. The package already bundles the necessary QCF fonts. No extra asset setup is required in your app.

Usage

Render a single ayah

import 'package:flutter/material.dart';
import 'package:qcf_quran/qcf_quran.dart';

class SingleVerseDemo extends StatelessWidget {
  const SingleVerseDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return const Directionality(
      textDirection: TextDirection.rtl,
      child: QcfVerse(
        surahNumber: 1, // Al-Fatiha
        verseNumber: 1,
      ),
    );
  }
}

Full mushaf with paging

MaterialApp(
  home: Scaffold(
    body: PageviewQuran(
      initialPageNumber: 1,
      onPageChanged: (page) {
        // Handle page change (1..604)
      },
    ),
  ),
);

Full mushaf with paging (responsive with ScreenUtil)

import 'package:flutter_screenutil/flutter_screenutil.dart';
import 'package:qcf_quran/qcf_quran.dart';

// inside a build method (ensure you've initialized ScreenUtil)
PageviewQuran(
  initialPageNumber: 1,

  ///sp for responsiveness
  sp: 1.sp,

  ///h for responsiveness
  h: 1.h,
  textColor: Colors.black,
  onLongPress: (surah, verse) {
    print("Long Pressed on verse $surah:$verse");
  },
  onLongPressUp: (surah, verse) {
    print("Long Press Up on verse $surah:$verse");
  },
  onLongPressCancel: (surah, verse) {
    print("Long Press Cancel on verse $surah:$verse");
  },
  onLongPressDown: (surah, verse, details) {
    print(
        "Long Press Down on verse $surah:$verse @ ${details.globalPosition}");
  },
),

Querying data

final page = getPageNumber(2, 255); // page of Al-Baqarah 2:255 (Ayat al-Kursi)
final nameAr = getSurahNameArabic(2); // البقرة
final juz = getJuzNumber(2, 255); // 3

final results = searchWords('الرحمن');
// { occurences: <int>, result: [ {suraNumber: 1, verseNumber: 3}, ... ] }

Example app

See example/ for a runnable demo that uses:

  • PageviewQuran with RTL paging and per-page fonts
  • QcfVerse to show a single ayah
  • Page jump dialog and a basic Arabic search powered by searchWords(…)

Run it with:

flutter run -d <device>

Screenshots

Quran page view Search and verse

API overview

  • Rendering widgets:
    • QcfVerse(surahNumber, verseNumber, fontSize?, textColor?, backgroundColor?, …)
    • PageviewQuran(initialPageNumber?, controller?, onPageChanged?, fontSize?, textColor?, pageBackgroundColor?, verseBackgroundColor?, onLongPress?, …)
  • Data & utilities:
    • Counts: totalPagesCount, totalSurahCount, totalJuzCount, totalVerseCount
    • Lookup: getPageData(page), getPageNumber(surah, verse), getVerse(…)/getVerseQCF(…), getVerseNumberQCF(…)
    • Names: getSurahName(…)/English/Arabic, getPlaceOfRevelation(…)
    • Search: searchWords(…)
    • Text helpers: normalise(…), removeDiacritics(…)

Notes

  • The fonts are page-specific. Always use the page’s font family (handled internally by QcfVerse and PageviewQuran).
  • searchWords(…) is a simple text search and returns up to 50 matches.
  • Directionality is right-to-left for both verse and page view rendering.
  • For optimal responsiveness and layout, use flutter_screenutil and pass sp and h to PageviewQuran (e.g., sp: 1.sp, h: 1.h). Ensure ScreenUtil is initialized in your app.

QCF fonts

  • This package bundles 604 per-page QCF font files as WOFF under families named QCF_P001 … QCF_P604.
  • Verse-related glyphs (e.g., basmala/verse marks) are provided via the QCF_BSML family.
  • Widgets QcfVerse and PageviewQuran resolve and apply the correct per-page family for you; no manual font selection is needed.
  • Avoid mixing fonts across pages. Using the page’s matching family ensures ligatures and glyph positions match the official mushaf.

License

MIT for code. QCF fonts are provided by King Fahd Complex for the Printing of the Holy Quran (KFGQPC). Ensure you comply with their terms when distributing applications.

Credits

  • QCF fonts by KFGQPC
  • Data mapping for pages, surahs, and juz sourced from included datasets in lib/src/data/

Libraries

qcf_quran
qcf_quran — High-fidelity Quran Mushaf rendering using bundled QCF fonts.