qcf_quran_plus 0.1.1
qcf_quran_plus: ^0.1.1 copied to clipboard
offline Quran package with Hafs font and have tajweed.
๐ 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
QcfFontLoaderfor startup font initialization- Page font preloading around the current page
- Cached word/line offsets
- Parsed line caching
RepaintBoundaryaround 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
ayahStyleunless 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:
textColorbackgroundColor- 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.
Deferred Page Construction #
QuranPageView supports deferred page construction to improve performance during rapid page navigation.
When enabled, newly appearing Quran pages are not fully built while the user is actively swiping. Their content is rendered after scrolling has settled.
This can reduce unnecessary page construction and help keep page navigation smooth, especially on devices where Quran page rendering is relatively expensive.
The feature is enabled by default:
QuranPageView(
pageController: _controller,
highlights: _activeHighlights,
isDarkMode: false,
deferNewPages: true,
deferDelay: const Duration(milliseconds: 50),
);
deferNewPages
Controls whether newly appearing pages should defer their content construction while the user is scrolling.
deferNewPages: true,
When true, pages that appear during an active swipe are temporarily kept lightweight. Their Quran content is built after scrolling has settled.
The currently displayed page remains available while navigating.
The default value is:
true
To disable deferred page construction and build pages immediately:
QuranPageView(
pageController: _controller,
highlights: _activeHighlights,
isDarkMode: false,
deferNewPages: false,
);
You can also change this value at runtime.
deferDelay
Controls how long QuranPageView waits after scrolling ends before deferred page content is built.
The default value is:
const Duration(milliseconds: 50)
Example:
QuranPageView(
pageController: _controller,
highlights: _activeHighlights,
isDarkMode: false,
deferNewPages: true,
deferDelay: const Duration(milliseconds: 50),
);
You can increase the delay if you want to wait longer before constructing pages after a swipe:
QuranPageView(
pageController: _controller,
highlights: _activeHighlights,
isDarkMode: false,
deferNewPages: true,
deferDelay: const Duration(milliseconds: 100),
);
If the user starts another swipe before deferDelay finishes, the pending page build is cancelled and the delay starts again after the new scrolling operation ends.
This prevents pages from being unnecessarily constructed while the user is rapidly flipping through multiple Quran pages.
deferDelay is only used when:
deferNewPages: true
The deferred page construction optimization works with both the single-page and two-page layouts. #
๐งฉ 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 = getaya_noQCF(
2,
255,
);
getaya_noQCF 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
getaya_noQCF
๐๏ธ Typical Application Architecture #
qcf_quran_plus is designed to fit into common Flutter architectures.
You can keep Quran UI state in:
setStateBloc / CubitProviderRiverpod- 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 getaya_noQCF 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.