react-native-quran-tajweed

Offline Quran text with tajweed coloring for React Native — including tafkhim/tarqiq (heavy/light ra' and the constant isti'la' letters) for all 6236 verses. Zero runtime network: all data and fonts are bundled.

• 📖 All 114 surahs, pre-parsed at build time — O(1) synchronous lookup
• 🎨 Rule names in the data, colors resolved at render time — fully themeable
• 🟠 Tafkhim/tarqiq baked in (computed once in the pipeline, never on device)
• 🔤 Bundled Scheherazade New font (SIL, OFL 1.1)
• 🧩 Composable primitives — drop-in components or raw segments for custom UIs (e.g. blur-on-touch)

Data source: the text_uthmani_tajweed field from the Quran.com API, pre-processed offline. Tafkhim/tarqiq is computed by this project. v1 annotates the wasl (continuous) reading.

Installation

npm install react-native-quran-tajweed

Font setup

The package ships the OFL-licensed Scheherazade New font. Register it once.

Expo — add to app.json:

{
  "expo": {
    "plugins": [
      ["expo-font", {
        "fonts": [
          "node_modules/react-native-quran-tajweed/assets/fonts/ScheherazadeNew-Regular.ttf",
          "node_modules/react-native-quran-tajweed/assets/fonts/ScheherazadeNew-Bold.ttf"
        ]
      }]
    ]
  }
}

Bare React Native — add to react-native.config.js, then run npx react-native-asset:

module.exports = {
  assets: ['./node_modules/react-native-quran-tajweed/assets/fonts/'],
};

Prefer mushaf-exact Uthmanic glyphs? Install your own font (e.g. a KFGQPC font) and pass fontFamily="...". The package never auto-registers fonts.

Basic usage

import { QuranVerse } from 'react-native-quran-tajweed';

export function Fatiha() {
  return <QuranVerse surah={1} ayah={1} fontSize={32} />;
}

For a whole short surah:

import { QuranSurah } from 'react-native-quran-tajweed';

<QuranSurah surah={112} />;

For long surahs (e.g. Al-Baqarah), prefer a FlatList/FlashList of <QuranVerse/> rows — QuranSurah renders every verse eagerly.

Blur-on-touch (memorization)

The package renders measurable text into a container you control. Compose the blur yourself:

import { useState } from 'react';
import { Pressable, StyleSheet } from 'react-native';
import { BlurView } from 'expo-blur';
import { QuranVerse } from 'react-native-quran-tajweed';

function HiddenVerse({ surah, ayah }: { surah: number; ayah: number }) {
  const [revealed, setRevealed] = useState(false);
  return (
    <Pressable onPress={() => setRevealed(true)}>
      <QuranVerse surah={surah} ayah={ayah} />
      {!revealed && <BlurView intensity={20} style={StyleSheet.absoluteFill} />}
    </Pressable>
  );
}

getAyahSegments is synchronous, so revealing causes no async flicker. Use getAyahText for a plain-text placeholder.

Component API

<QuranVerse />

| Prop | Type | Default | Notes | |---|---|---|---| | surah | number | — | required | | ayah | number | — | required | | fontSize | number | 28 | | | fontFamily | string | 'Scheherazade New' | | | colorMap | Partial<TajweedColorMap> | — | override specific rule colors | | showVerseNumber | boolean | true | Arabic-Indic numeral | | onPress | () => void | — | wraps content in a Pressable | | style | StyleProp<TextStyle> | — | | | containerStyle | StyleProp<ViewStyle> | — | |

Returns null if the surah/ayah is out of range.

<QuranSurah />

surah, fontSize, fontFamily, colorMap, showVerseNumbers, containerStyle, and renderVerse?: (ayah, segments) => ReactNode for full row control.

<QuranWord />

The lowest-level primitive — renders an array of TajweedSegments. Props: segments, fontSize, fontFamily, colorMap, style.

Custom color theme

import { QuranVerse, DEFAULT_TAJWEED_COLORS } from 'react-native-quran-tajweed';

<QuranVerse
  surah={1}
  ayah={1}
  colorMap={{ tafkhim: '#C2410C', tarqiq: '#0EA5E9' }} // tarqiq is off by default
/>;

When a segment carries multiple rules (e.g. a madd letter that is also tafkhim), resolveColor picks the displayed color by RULE_PRIORITY — tag rules outrank tafkhim; tarqiq defaults to no color (standard mushaf convention).

Utilities

import {
  getAyahSegments,   // (surah, ayah) => TajweedSegment[] | null
  getAyahText,       // (surah, ayah) => string | null  (plain normalized text)
  getSurahSegments,  // (surah) => { ayah, segments }[] | null
  getSurahAyahCount, // (surah) => number | null
  resolveColor,      // (rules, colorMap?) => string | null
  DEFAULT_TAJWEED_COLORS,
  RULE_PRIORITY,
} from 'react-native-quran-tajweed';

Tajweed rules

ghunnah, ikhafa, ikhafa_shafawi, idgham_ghunnah, idgham_wo_ghunnah, idgham_shafawi, idgham_mutajanisayn, idgham_mutaqaribayn, iqlab, qalaqah, madda_normal, madda_permissible, madda_obligatory, madda_necessary, ham_wasl, laam_shamsiyah, slnt, tafkhim, tarqiq.

Data & accuracy

Tajweed tags come from Quran.com (Hafs ʿan ʿAsim). Tafkhim/tarqiq is computed by this project's pipeline and verified with a regression suite covering every ra' rule branch (vowels, sukun chains, the isti'la' barrier, hamzat al-wasl). v1 colors the wasl reading; waqf-only colorings are out of scope. Found a discrepancy? Open an issue with surah, ayah, expected rule, and a reference source.

License

MIT (code). The bundled Scheherazade New font is licensed under the SIL Open Font License 1.1 — see assets/fonts/OFL.txt.