Package Title

react-native-quran-hafs

Package description

It's a simple package allowing you to display the quran as mushaf

Features

• Display the quran like mushaf.
• Selected a single verse to copy or bookmark it.
• Use this method [_renderChapterName(chapterId)] to render the surah name like mushaf.
• Use this method [_renderChapterAyahs(chapterId)] to render the number of surah verses(Ayahs).
• Scroll to a specific verse(Ayah) page.
• Support RTL Or LTR.
• NEW in v1.4.0: Background font preloading for instant page loads
• NEW in v1.4.0: Batch font downloads with progress tracking
• NEW in v1.4.0: Font cache management utilities

🚀 Font Preloading (New in v1.4.0)

Dramatically improve loading performance by preloading Quran fonts in the background!

Quick Start

import { useQuranFontPreloader, PRIORITY_PAGES } from 'react-native-quran-hafs';

function QuranListScreen() {
  const { isPreloading, progress } = useQuranFontPreloader({
    pages: PRIORITY_PAGES,
    quranFontApi: 'https://raw.githubusercontent.com/quran/quran.com-images/master/fonts/',
    autoStart: true,
  });

  return (
    <View>
      {isPreloading && (
        <Text>Preparing Quran: {progress.percentage}%</Text>
      )}
      {/* Your Surah list */}
    </View>
  );
}

Advanced Usage

Batch Download Specific Pages

import { downloadMultiplePageFonts } from 'react-native-quran-hafs';

const pages = [1, 2, 293, 294, 295]; // Al-Fatihah + start of Al-Kahf

await downloadMultiplePageFonts(
  pages,
  'https://raw.githubusercontent.com/quran/quran.com-images/master/fonts/',
  (current, total, page) => {
    console.log(`Downloaded ${current}/${total} - Page ${page}`);
  }
);

Check Cache Status

import { isFontCached, getFontCacheStats } from 'react-native-quran-hafs';

// Check single page
const isCached = await isFontCached(1); // true/false

// Get cache statistics
const stats = await getFontCacheStats();
console.log(`Cached: ${stats.totalCached} fonts`);

Clear Cache

import { clearFontCache } from 'react-native-quran-hafs';

// Clear all fonts
await clearFontCache();

// Clear specific pages
await clearFontCache([1, 2, 3]);

Priority Pages

Pre-defined page groups for common use cases:

import {
  PRIORITY_PAGES,    // 53 most-read pages
  JUZ_30_PAGES,      // Juz 30 (pages 582-604)
  AL_FATIHAH_PAGES,  // Al-Fatihah (pages 1-2)
  AL_KAHF_PAGES,     // Al-Kahf (pages 293-304)
  YASIN_PAGES,       // Yasin (pages 440-445)
  AL_MULK_PAGES,     // Al-Mulk (pages 562-564)
  AR_RAHMAN_PAGES,   // Ar-Rahman (pages 531-534)
  ALL_QURAN_PAGES,   // All 604 pages
} from 'react-native-quran-hafs';

Preinstallation

• Install this font family QCF_BSML and change its extention to be .ttf not .TTF

• install these packages:

  • @react-native-clipboard/clipboard.
  • @react-native-community/slider.
  • axios.
  • react-native-dynamic-fonts.
  • react-native-fs.
  • react-native-responsive-fontsize.
  • react-native-track-player.

• Upload the fonts files as it is to you server so it can be easily downloaded

• The fonts url example https://your-domain/fonts/

How to install and run

npm install react-native-quran-hafs
cd ios
pod install
cd ..
npm run ios

Apis

| Option | Description | Type | Required | | ------------------------- | ------------------------------------------------------------------------------------- | ---------------------------- | -------- | | chapterId | The surah or juz id | number | true | | type | It's a type of what you want to display (surah or juz) | QuranTypesEnums | true | | QURAN_FONTS_API | Fonts url uploaded to your server | string | true | | backgroundImage | The background of mushaf screen | ImageSourcePropType | false | | surahNameFrameImage | The frame of surah name | ImageSourcePropType | false | | onBookMarkedVerse | Callback funtion that return verse as ISurahVerse | (verse: ISurahVerse) => void | false | | selectedBookedMarkedVerse | The verse object returned by onBookMarkedVerse function to scroll to passed ayah page | ISurahVerse | false | | resizeImageBackgroundMode | It's a resize mode of mushaf background image | ImageResizeMode | false | | selectionColor | It's a color when select a specific ayah | ColorValue | false |

Usage Example

import {QuranPageLayout, QuranTypesEnums} from 'react-native-quran-hafs';
const App = () => {
  return (
    <QuranPageLayout
      chapterId={1}
      type={QuranTypesEnums.chapter} // QuranTypesEnums.juz
      QURAN_FONTS_API="https://your-domain/fonts/"
      onBookMarkedVerse={verse => console.log(verse)}
    />
  );
};
export default App;

How to:

• Automatic scrolling to specific verse:

<QuranPageLayout
      chapterId={67}
      type={QuranTypesEnums.chapter}
      QURAN_FONTS_API="https://your-domain/fonts/"
      selectedBookedMarkedVerse={{
        chapter_code_v1: 194,
        chapter_id: 67,
        id: 5263,
        page_number: 563,
        text_uthmani:
          'أَفَمَن يَمْشِى مُكِبًّا عَلَىٰ وَجْهِهِۦٓ أَهْدَىٰٓ أَمَّن يَمْشِى سَوِيًّا عَلَىٰ صِرَٰطٍ مُّسْتَقِيمٍ',
        verse_font_famliy: 'QCF_P563',
        verse_key: '67:22',
        verse_number: 22,
      }}
      onBookMarkedVerse={verse => {
        console.log(verse);
      }}
    />