Documentation Index Fetch the complete documentation index at: https://mintlify.com/adelpro/quran-search-engine/llms.txt
Use this file to discover all available pages before exploring further.
Install the package
Complete the installation to add quran-search-engine to your project.
Load the data
Load the Quran dataset, morphology map, and word map at app startup: import { search , loadMorphology , loadQuranData , loadWordMap , type SearchResponse , } from 'quran-search-engine' ; const [ quranData , morphologyMap , wordMap ] = await Promise . all ([ loadQuranData (), loadMorphology (), loadWordMap (), ]); // Example output: // quranData.length => 6236 // morphologyMap.size => 6236 // Object.keys(wordMap).length => (depends on dataset)
Examples assume an async context (Node 18+, ESM, or browser).
Perform a search
Use the search function with your query and loaded data: const response : SearchResponse = search ( 'الله الرحمن' , quranData , morphologyMap , wordMap , { lemma: true , root: true , }); response . results . forEach (( v ) => { console . log ( v . sura_id , v . aya_id , v . matchType , v . matchScore ); }); // Example output: // 1 1 exact 6 // 1 3 lemma 4
Search options The search function accepts the following options to control matching behavior:
Option Type Description lemmabooleanEnable lemma-based matching (morphological analysis) rootbooleanEnable root-based matching (word etymology) fuzzybooleanEnable fuzzy fallback matching (optional, defaults to true)
Match scoring Each match type has a different score weight:
Match type Score per hit Exact +3 Lemma +2 Root +1 Fuzzy +0.5 (fallback only)
Control the number of results returned using pagination options:
const response = search ( 'الله الرحمن' , quranData , morphologyMap , wordMap , { lemma: true , root: true }, { page: 1 , limit: 10 }, );
The response includes pagination metadata:
response . pagination // => { totalResults: 42, totalPages: 5, currentPage: 1, limit: 10 }
Search response structure The SearchResponse object contains:
resultsScoredQuranText objects with match metadatacountspagination
Each result includes:
{ gid : number ; // Unique verse ID sura_id : number ; // Chapter number aya_id : number ; // Verse number uthmani : string ; // Uthmani script text standard : string ; // Standard Arabic text matchScore : number ; // Total match score matchType : MatchType ; // Best match type ('exact' | 'lemma' | 'root' | 'fuzzy') matchedTokens : string []; // Tokens that matched (for highlighting) // ... additional fields }
Next steps
Search API Explore all search options and advanced features
Highlighting Learn how to highlight matched text in your UI