🕌 qcf_quran_plus #

A lightweight, high-performance Flutter Quran package powered by the official QCF (Hafs) font.

Built for professional Quran, memorization, Tafsir, translation, audio, and Islamic applications, qcf_quran_plus provides a complete offline Quran rendering engine with:

• Authentic 604-page Mushaf rendering
• Single-page and two-page layouts
• Native QCF / Hafs rendering
• Uthmani Tajweed colors
• Light & Dark mode
• Ayah highlighting
• Word-level highlighting
• Interactive word tapping
• Long-press Ayah interactions
• Scrollable Surah List / Vertical Reader
• Smart Arabic search and normalization
• Quran page / Surah / Juz / Quarter / revelation metadata
• Optimized font loading and page preloading
• Custom builders for Surah headers, Basmallah, page headers, Ayah containers, top bars, and bottom bars

📸 Screenshots #

✨ Key Features #

📖 Authentic Mushaf Rendering #

Render the complete Quran using the package's QCF data and page engine.

• 604 Mushaf pages
• 114 Surahs
• 6,236 Ayahs
• 30 Juz
• Exact page-based rendering through QuranPageView
• Dedicated handling for the first two Mushaf pages
• Automatic Surah headers
• Automatic Basmallah rendering
• RTL Quran rendering
• Page-aware QCF font selection

The package's page engine works from structured QuranPage data and pre-parsed line information rather than rebuilding the Quran text from scratch on every frame.

⚡ High Performance & Offline Rendering #

qcf_quran_plus is designed for Quran applications where smooth rendering matters.

• Offline Quran data
• No network dependency for Quran rendering
• QcfFontLoader for startup font initialization
• Page font preloading around the current page
• Cached word/line offsets
• Parsed line caching
• RepaintBoundary around Quran pages
• Memoized indexes for Ayah and word highlights
• Optimized page construction for continuous swiping

For best results, initialize the fonts during your splash/loading phase before opening the Mushaf.

🎨 Uthmani Tajweed #

Enable native Tajweed rendering through:

isTajweed: true,

The page renderer selects the appropriate QCF font for the requested page and supports:

• Tajweed colors in Light mode
• Tajweed colors in Dark mode
• Non-Tajweed rendering when disabled
• Page-specific font selection
• Dark-mode-aware Quran text rendering

🌙 Light & Dark Mode #

Both Quran widgets support dark mode.

isDarkMode: Theme.of(context).brightness == Brightness.dark,

For the Mushaf page renderer, the package internally builds its QCF text style from the page number, Tajweed setting, and dark-mode setting.

Important: Avoid overriding ayahStyle unless you intentionally want to replace the package's default QCF style selection.

🎯 Dynamic Ayah Highlighting #

Use HighlightVerse to highlight any Ayah dynamically.

This is useful for:

• Audio synchronization
• Memorization sessions
• Bookmarks
• Active recitation
• Search results
• Tafsir navigation
• Temporary selection states

List<HighlightVerse> _activeHighlights = [];

setState(() {
  _activeHighlights = [
    HighlightVerse(
      surah: 2,
      verseNumber: 255,
      page: 42,
      color: Colors.amber.withValues(alpha: 0.4),
    ),
  ];
});

Clear the highlights:

setState(() {
  _activeHighlights = [];
});

The package indexes the supplied highlights internally so the Quran lines can determine which Ayahs are active without repeatedly scanning the whole list.

🖍️ Word-Level Highlighting #

The package also supports WordHighlight for highlighting individual words inside an Ayah.

You can control:

• textColor
• backgroundColor
• Surah
• Ayah
• Word index

Example:

final wordHighlights = <WordHighlight>[
  WordHighlight(
    surah: 2,
    verseNumber: 255,
    wordIndex: 3,
    textColor: Colors.white,
    backgroundColor: Colors.amber,
  ),
];

Pass the list directly to the page or Surah reader:

QuranPageView(
  pageController: controller,
  highlights: _activeHighlights,
  wordHighlights: wordHighlights,
  isDarkMode: isDark,
  isTajweed: true,
);

Word highlights are especially useful for:

• Word-by-word recitation tracking
• Quran teaching tools
• Pronunciation feedback
• Memorization assistants
• Vocabulary applications
• Audio word synchronization

👆 Word Interaction #

QuranPageView and QuranSurahListView expose onWordTap:

QuranPageView(
  pageController: controller,
  highlights: _activeHighlights,
  onWordTap: (surahNumber, verseNumber, wordIndex, word) {
    debugPrint(
      'Surah: $surahNumber | Ayah: $verseNumber | Word: $wordIndex | $word',
    );
  },
  isDarkMode: false,
  isTajweed: true,
);

This gives you the exact:

• Surah number
• Ayah number
• Word index
• Raw logical word

🤲 Long-Press Ayah Interaction #

Both Quran rendering modes support Ayah long press.

QuranPageView(
  pageController: controller,
  highlights: _activeHighlights,
  onLongPress: (surahNumber, verseNumber, details) {
    debugPrint(
      'Long pressed Surah $surahNumber, Ayah $verseNumber',
    );

    final position = details.globalPosition;

    // Show your own menu, bottom sheet, popup, tafsir dialog, etc.
    debugPrint('Pressed at: $position');
  },
  isDarkMode: false,
);

The callback gives you LongPressStartDetails, allowing you to build context menus relative to the exact press location.

Typical use cases:

• Copy Ayah
• Add bookmark
• Show Tafsir
• Start audio
• Share Ayah
• Start memorization
• Open translation

📖 Mushaf Page Mode #

Use QuranPageView when you need an authentic page-based Quran experience.

final PageController _controller = PageController(initialPage: 0);

List<HighlightVerse> _activeHighlights = [];

QuranPageView(
  pageController: _controller,
  highlights: _activeHighlights,
  isDarkMode: Theme.of(context).brightness == Brightness.dark,
  isTajweed: true,
  enableTwoPageLayout: true,

  onPageChanged: (pageNumber) {
    debugPrint('Navigated to page: $pageNumber');
  },

  onLongPress: (surahNumber, verseNumber, details) {
    debugPrint(
      'Long pressed Surah $surahNumber, Verse $verseNumber',
    );
  },
);

Single Page #

QuranPageView(
  pageController: _controller,
  highlights: _activeHighlights,
  isDarkMode: false,
  isTajweed: true,
  enableTwoPageLayout: false,
);

Two-Page Layout #

On wide screens, the package can render two Mushaf pages side-by-side:

QuranPageView(
  pageController: _controller,
  highlights: _activeHighlights,
  isDarkMode: false,
  isTajweed: true,
  enableTwoPageLayout: true,
);

The widget keeps the two-page controller synchronized with the external PageController.

🧩 Mushaf Customization #

QuranPageView supports custom builders for integrating Quran pages into your own application UI.

Top Bar #

QuranPageView(
  pageController: _controller,
  highlights: _activeHighlights,
  isDarkMode: false,
  topBar: const SizedBox(
    height: 50,
    child: Center(
      child: Text('Quran'),
    ),
  ),
);

Bottom Bar #

QuranPageView(
  pageController: _controller,
  highlights: _activeHighlights,
  isDarkMode: false,
  bottomBar: const SizedBox(
    height: 60,
    child: Center(
      child: Text('Player'),
    ),
  ),
);

Page Header #

QuranPageView(
  pageController: _controller,
  highlights: _activeHighlights,
  isDarkMode: false,
  pageHeaderBuilder: (context, pageNumber) {
    return Text('Page $pageNumber');
  },
);

Custom Surah Header #

QuranPageView(
  pageController: _controller,
  highlights: _activeHighlights,
  isDarkMode: false,
  surahHeaderBuilder: (context, surahNumber) {
    return Text(
      getSurahNameArabic(surahNumber),
      style: const TextStyle(
        fontSize: 24,
        fontWeight: FontWeight.bold,
      ),
    );
  },
);

Custom Basmallah #

QuranPageView(
  pageController: _controller,
  highlights: _activeHighlights,
  isDarkMode: false,
  basmallahBuilder: (context, surahNumber) {
    return const Text(
      'بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ',
    );
  },
);

Custom Text Style #

ayahStyle is available when you intentionally want to override the package's default Quran text style:

QuranPageView(
  pageController: _controller,
  highlights: _activeHighlights,
  isDarkMode: false,
  ayahStyle: const TextStyle(
    fontSize: 42,
  ),
);

Because ayahStyle overrides the default QCF style, use it carefully when relying on page-specific QCF font selection.

Background #

QuranPageView(
  pageController: _controller,
  highlights: _activeHighlights,
  isDarkMode: false,
  pageBackgroundColor: const Color(0xFFFBF6EE),
);

📜 Vertical Surah List Mode #

Use QuranSurahListView for continuous Surah reading.

This mode is especially useful for:

• Tafsir
• Translation
• Audio players
• Memorization
• Word-level interactions
• Custom Ayah cards
• Teaching interfaces

final ItemScrollController _itemScrollController =
    ItemScrollController();

final List<HighlightVerse> _highlights = [];

QuranSurahListView(
  surahNumber: 1,
  itemScrollController: _itemScrollController,
  highlights: _highlights,
  fontSize: 25,
  isTajweed: true,
  isDarkMode: Theme.of(context).brightness == Brightness.dark,
);

🎨 Fully Customizable Ayah Cards #

QuranSurahListView exposes ayahBuilder with all important Ayah information.

QuranSurahListView(
  surahNumber: 2,
  highlights: _highlights,
  fontSize: 25,
  isTajweed: true,
  isDarkMode: false,
  ayahBuilder: (
    context,
    surahNumber,
    verseNumber,
    pageNumber,
    ayahWidget,
    isHighlighted,
    highlightColor,
  ) {
    return AnimatedContainer(
      duration: const Duration(milliseconds: 250),
      padding: const EdgeInsets.all(16),
      decoration: BoxDecoration(
        color: isHighlighted
            ? highlightColor.withValues(alpha: 0.15)
            : Colors.transparent,
        borderRadius: BorderRadius.circular(16),
      ),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          Text(
            'Ayah $verseNumber • Page $pageNumber',
            style: const TextStyle(
              color: Colors.grey,
            ),
          ),
          const SizedBox(height: 8),
          ayahWidget,
        ],
      ),
    );
  },
);

The builder receives:

BuildContext
surahNumber
verseNumber
pageNumber
ayahWidget
isHighlighted
highlightColor

This lets you build your own:

• Audio controls
• Bookmark buttons
• Translation containers
• Tafsir cards
• Recitation feedback
• Memorization UI
• Ayah statistics

🔎 Smart Offline Arabic Search #

The package includes a lightweight Quran search engine.

Normalize User Input #

final query = normalise('الرحمن');

Search #

final results = searchWords(query);

debugPrint(
  'Matches: ${results['occurences']}',
);

for (final match in results['result']) {
  final surah = match['sora'];
  final ayah = match['aya_no'];
  final text = match['text'];

  debugPrint(
    '${getSurahNameArabic(surah)} : $ayah => $text',
  );
}

The search engine supports:

• Diacritic-insensitive matching
• Arabic normalization
• Alef normalization
• Ya normalization
• Hamza/Alef variants normalization
• Whitespace normalization
• Search without depending on network requests
• Emlaey search first
• Othmanic fallback when no Emlaey match exists
• Configurable result limit

Example:

final results = searchWords(
  'وتلك حدود',
  limit: 20,
);

The search logic can match phrases after removing spaces and standardizing Arabic forms.

🧹 Text Normalization Helpers #

normalise #

General Quran-oriented normalization:

final cleaned = normalise(text);

It removes Quranic annotation characters and common Arabic variants before comparison.

normalizeArabicText #

The package also exposes:

final cleaned = normalizeArabicText(text);

This normalization removes basic Arabic diacritics and standardizes selected Arabic letter forms.

removeDiacritics #

For lightweight diacritic removal:

final cleaned = removeDiacritics(text);

This is useful for:

• Search
• Comparison
• Matching user input
• Simplified text processing

📊 Quran Statistics & Constants #

The package exposes common Quran constants:

totalPagesCount;   // 604
totalSurahCount;   // 114
totalVerseCount;   // 6236
totalJuzCount;     // 30

totalMakkiSurahs;  // 89
totalMadaniSurahs; // 25

🧭 Page & Surah Metadata #

Get Page Data #

final data = getPageData(42);

Surah Count on a Page #

final count = getSurahCountByPage(42);

Ayah Count on a Page #

final count = getVerseCountByPage(42);

Get Surah Names #

getSurahName(1);        // Transliteration/name
getSurahNameEnglish(1); // English
getSurahNameArabic(1);  // Arabic

Revelation Place #

getPlaceOfRevelation(1); // Makkah or Madinah

Verse Count #

getVerseCount(1); // Number of Ayahs in the Surah

📍 Quran Location Helpers #

Find the Page of an Ayah #

final page = getPageNumber(2, 255);

Find the Juz #

final juz = getJuzNumber(2, 255);

Find the Quarter #

final quarter = getQuarterNumber(2, 255);

These helpers make it easy to build:

• Ayah details dialogs
• Audio players
• Bookmarks
• Search result navigation
• Memorization navigation
• Tafsir navigation

🕌 Hizb & Quarter Helpers #

Show Only When a New Quarter Starts on the Page #

final text = getHizbTextByPage(
  42,
  isArabic: true,
);

Returns an empty string when no new quarter starts exactly on that page.

Get the Current Hizb/Quarter for a Page #

final text = getCurrentHizbTextForPage(
  42,
  isArabic: true,
);

Unlike the exact-page helper, this also resolves the currently active quarter when it started on a previous page.

English output is available:

getCurrentHizbTextForPage(
  42,
  isArabic: false,
);

📖 Verse Text Helpers #

Get Verse Text #

final verse = getVerse(2, 255);

Get Verse-End Symbol #

final symbol = getVerseEndSymbol(
  255,
  arabicNumeral: true,
);

Get the QCF Ayah Glyph #

final glyph = getAyaNoQCFLite(
  2,
  255,
);

Cached QCF Ayah Glyph Lookup #

final glyph = getAyaNoQCF(
  2,
  255,
);

getAyaNoQCF keeps an internal cache so repeated Ayah-ending glyph lookups do not repeatedly scan the Quran dataset.

🚀 Font Initialization #

For the smoothest first render, initialize QCF fonts before entering the Quran screen.

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

  @override
  State<SplashScreen> createState() => _SplashScreenState();
}

class _SplashScreenState extends State<SplashScreen> {
  @override
  void initState() {
    super.initState();
    _initializeFonts();
  }

  Future<void> _initializeFonts() async {
    await QcfFontLoader.setupFontsAtStartup(
      onProgress: (progress) {
        debugPrint(
          'Font loading: ${(progress * 100).toStringAsFixed(1)}%',
        );
      },
    );

    if (!mounted) return;

    Navigator.pushReplacement(
      context,
      MaterialPageRoute(
        builder: (_) => const QuranScreen(),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(
        child: CircularProgressIndicator(),
      ),
    );
  }
}

The font loader exposes page preloading as well:

QcfFontLoader.preloadPages(
  42,
  radius: 3,
);

You can use this when changing pages or building your own advanced Quran navigation flow.

📦 Installation #

Add the package to pubspec.yaml:

dependencies:
  qcf_quran_plus: ^latest_version
  scrollable_positioned_list: ^0.3.8

Then:

flutter pub get

Import:

import 'package:qcf_quran_plus/qcf_quran_plus.dart';

🧩 Public API Overview #

Widgets #

QuranPageView
QuranSurahListView

Models #

HighlightVerse
WordHighlight
Ayah
QuranPage
Surah

Quran Data #

quran
pageData
suwar
juz
quarters

Utilities #

QuranTextStyles
QcfFontLoader

Search & Normalization #

searchWords
normalise
normalizeArabicText
removeDiacritics

Metadata #

getPageData
getSurahCountByPage
getVerseCountByPage
getSurahName
getSurahNameEnglish
getSurahNameArabic
getPlaceOfRevelation
getVerseCount
getPageNumber
getJuzNumber
getQuarterNumber
getHizbTextByPage
getCurrentHizbTextForPage

Verse Helpers #

getVerse
getVerseEndSymbol
getAyaNoQCFLite
getAyaNoQCF

🏗️ Typical Application Architecture #

qcf_quran_plus is designed to fit into common Flutter architectures.

You can keep Quran UI state in:

• setState
• Bloc / Cubit
• Provider
• Riverpod
• Any other state-management solution

For example:

class QuranController extends ChangeNotifier {
  List<HighlightVerse> highlights = [];

  void highlightAyah({
    required int surah,
    required int ayah,
    required int page,
    required Color color,
  }) {
    highlights = [
      ...highlights,
      HighlightVerse(
        surah: surah,
        verseNumber: ayah,
        page: page,
        color: color,
      ),
    ];

    notifyListeners();
  }
}

Then pass the current state directly to the Quran widget.

⚡ Performance Recommendations #

1. Initialize Fonts Early #

Use:

QcfFontLoader.setupFontsAtStartup(...)

during splash/loading.

when implementing custom navigation or page tracking.

3. Keep Highlight State External #

Store HighlightVerse and WordHighlight in your application state and update them as needed.

4. Let the Package Control QCF Styling #

For authentic Mushaf rendering, prefer:

isTajweed: true,
isDarkMode: isDark,

without replacing ayahStyle unless you specifically need a custom text style.

5. Use getAyaNoQCF for Repeated Glyph Lookups #

Its internal cache is useful when rendering large Ayah lists.

🧱 Built For #

qcf_quran_plus is suitable for:

• 📖 Quran reading applications
• 🧠 Quran memorization applications
• 🎧 Audio-synced Quran players
• 🗣️ Recitation and pronunciation tools
• 🎨 Tajweed learning interfaces
• 🔍 Quran search applications
• 📚 Tafsir applications
• 🌍 Quran translation interfaces
• 📊 Quran statistics and metadata screens
• 🕌 Islamic educational applications

📄 License #

Distributed under the MIT License.

See LICENSE for more information.

❤️ Made for Serious Quran Applications #

qcf_quran_plus combines an authentic page-based Mushaf renderer with a flexible vertical reader, interactive Ayah and word highlighting, offline Arabic search, metadata helpers, and a performance-oriented QCF font engine.

Built with Flutter for developers who want to focus on their Quran application instead of rebuilding the Quran rendering layer from scratch.