qcf_quran_plus 0.1.0 copy "qcf_quran_plus: ^0.1.0" to clipboard
qcf_quran_plus: ^0.1.0 copied to clipboard

Published 14 days ago
SDKFlutter
PlatformAndroidiOSLinuxmacOSWindows
โ†’

Metadata

offline Quran package with Hafs font and have tajweed.

More...

๐Ÿ•Œ qcf_quran_plus #

Pub Version Flutter License: MIT

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 #

Mushaf View Tajweed Support

Surah List Mode Dark Mode

Search Engine Metadata Details

โœจ 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('ุงู„ุฑุญู…ู†');

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.

โ† Metadata

26
likes
160
points
3.35k
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Metadata

offline Quran package with Hafs font and have tajweed.

Homepage
Repository (GitHub)
View/report issues

License

MIT (license)

Dependencies

archive, flutter, path_provider, scrollable_positioned_list

More

Packages that depend on qcf_quran_plus

Back