islam.js

[![npm package][npm-img]][npm-url] [![Build Status][build-img]][build-url] [![Downloads][download-img]][npm-url] [![Issues][issues-img]][issues-url] [![Code Coverage][codecov-img]][codecov-url] [![Semantic Release][semantic-release-img]][semantic-release-url]

islam.js is a comprehensive JavaScript/TypeScript library designed for Islamic applications. It provides functionalities related to the Quran, Hadith, Dua & Azkar, Prayer Timings, and Hijri Calendar. This package offers multilingual support, a wide range of Tafseers, Hadith collections, and tools to enhance the development of Islamic software solutions.

---

Features

• Quran:

  • Support for Dialects: Hafs and Warsh
  • 28 Language Translations
  • 28 Tafseers (Commentaries) in different languages

• Hadith:

  • Collections: Kutub al-Sittah (Six Authentic Books) with 5+ Translations

• Dua & Azkar:

  • 134 categories with over 360 Azkars (supplications)

• Prayer Timings:

  • Accurate prayer timings for any location worldwide

• Hijri Calendar:

  • Hijri date conversion and calendar utilities

Installation

To install islam.js, use npm or yarn:

npm install islam.js
# or
yarn add islam.js

Getting Started

Import the library into your JavaScript or TypeScript project and start using the available features.

import { Quran, Hadith } from 'islam.js';

Usage

1. Quran

Supported Translation Languages

| Language | TranslationEnum value | |---|---| | Albanian | TranslationEnum.Albanian | | Bulgarian | TranslationEnum.Balgarian | | Bengali | TranslationEnum.Bengali | | Chinese | TranslationEnum.Chinese | | Dutch | TranslationEnum.Dutch | | English | TranslationEnum.English | | French | TranslationEnum.French | | German | TranslationEnum.German | | Hindi | TranslationEnum.Hindi | | Indonesian | TranslationEnum.Indonesian | | Italian | TranslationEnum.Italian | | Japanese | TranslationEnum.Japanese | | Korean | TranslationEnum.Korean | | Norwegian | TranslationEnum.Norwegian | | Pashto | TranslationEnum.Pashto | | Persian | TranslationEnum.Persian | | Portuguese | TranslationEnum.Portuguese | | Punjabi | TranslationEnum.Punjabi | | Romanian | TranslationEnum.Romanian | | Russian | TranslationEnum.Russian | | Sindhi | TranslationEnum.Sindhi | | Somalian | TranslationEnum.Somalian | | Spanish | TranslationEnum.Spanish | | Tamil | TranslationEnum.Tamil | | Thai | TranslationEnum.Thai | | Turkish | TranslationEnum.Turkish | | Urdu | TranslationEnum.Urdu | | Uzbek | TranslationEnum.Uzbek |

Get a chapter by index

import { Quran } from 'islam.js';
const quran = new Quran();
const chapter = quran.getChapterByIndex(108);
console.log(chapter);

//Output
{
   "name": "الكوثر",
   "type": "مكيّة",
   "englishName": "Al-Kawthar",
   "number": 108,
   "numberOfLetters": 42,
   "numberOfVerses": 3,
   "numberOfWords": 10,
   "verses": [
      "إِنَّا أَعْطَيْنَاكَ الْكَوْثَرَ",
      "فَصَلِّ لِرَبِّكَ وَانْحَرْ",
      "إِنَّ شَانِئَكَ هُوَ الْأَبْتَرُ"
   ]
}

Get a chapter by name

By default the dialect will be Hafs but we can change it to Warsh as well.

import { Quran, DialectEnum } from 'islam.js';
const quran = new Quran(DialectEnum.Warsh);
const chapter = quran.getChapterByName('Al-Ekhlas');
console.log(chapter);

//Output
{
   "name": "الإخلاص",
   "type": "مكيّة",
   "englishName": "Al-Ekhlas",
   "number": 112,
   "numberOfLetters": 47,
   "numberOfVerses": 4,
   "numberOfWords": 15,
    "verses": [
      "قُلْ هُوَ اللَّهُ أَحَدٌ",
      "اللَّهُ الصَّمَدُ",
      "لَمْ يَلِدْ وَلَمْ يُولَدْ",
      "وَلَمْ يَكُن لَّهُ كُفُوًا أَحَدٌ"
   ]
}

Get a verse by chapterNo and verseNo

import { Quran } from 'islam.js';
const quran = new Quran();
const verse = quran.getVerse(21, 107);
console.log(verse);

//Output
'وَمَا أَرْسَلْنَاكَ إِلَّا رَحْمَةً لِّلْعَالَمِينَ'

Get multiple verses with translation

import { Quran } from 'islam.js';
const quran = new Quran();
const verse =  quran.getMultipleVersesWithTranslation([{ chapterNo: 21, verseNo: 107 }]);
console.log(verse);

//Output
[
   {
      "verse": "وَمَا أَرْسَلْنَاكَ إِلَّا رَحْمَةً لِّلْعَالَمِينَ",
      "translation": "And We have not sent you, [O Muhammad], except as a mercy to the worlds."
   }
]

We can specify a different language for translation as well.

import { Quran, TranslationEnum } from 'islam.js';
const quran = new Quran();
const verse =  quran.getMultipleVersesWithTranslation([{ chapterNo: 21, verseNo: 107 }], TranslationEnum.French);
console.log(verse);

//Output
[
   {
      "verse": "وَمَا أَرْسَلْنَاكَ إِلَّا رَحْمَةً لِّلْعَالَمِينَ",
      "translation": "Et Nous ne t'avons envoyé qu'en miséricorde pour l'univers."
   }
]

Get random verse with translation

import { Quran } from 'islam.js';
const quran = new Quran();
const verse =  quran.getRandomVerseWithTranslation();
console.log(verse);

//Output
{
   "chapter": "الزمر",
   "verseNo": 53,
   "verse": "۞ قُلْ يَا عِبَادِيَ الَّذِينَ أَسْرَفُوا عَلَىٰ أَنفُسِهِمْ لَا تَقْنَطُوا مِن رَّحْمَةِ اللَّهِ ۚ إِنَّ اللَّهَ يَغْفِرُ الذُّنُوبَ جَمِيعًا ۚ إِنَّهُ هُوَ الْغَفُورُ الرَّحِيمُ",
   "translation": "Say, 'O My servants who have transgressed against themselves [by sinning], do not despair of the mercy of Allah.Indeed, Allah forgives all sins. Indeed, it is He who is the Forgiving, the Merciful.'"
}

Get a verse with translation and tafseer

import { Quran, TranslationEnum, TafseerEnum } from 'islam.js';
const quran = new Quran();
const verse = await quran.getVerseWithTranslationAndTafseer(53, 39, TranslationEnum.Urdu, TafseerEnum.TafsirBayanulQuran)
console.log(verse);

//Output
{
   "verse": "وَأَن لَّيْسَ لِلْإِنسَانِ إِلَّا مَا سَعَىٰ",
   "translation": "اور یہ کہ انسان کو وہی ملتا ہے جس کی وہ کوشش کرتا ہے",
   "tafseer": "آیت 39{ وَاَنْ لَّــیْسَ لِلْاِنْسَانِ اِلَّا مَا سَعٰی۔ } ”اور یہ کہ انسان کے لیے نہیں ہے مگر وہی کچھ جس کی اس نے سعی کی ہوگی۔“ انسان کو جو کچھ کرنا ہوگا اپنی محنت اور کوشش کے بل پر کرنا ہوگا ‘ خواہشوں اور تمنائوں سے کچھ نہیں ہوگا۔ قبل ازیں آیت 24 میں سوال کیا گیا تھا کہ ”کیا انسان کو وہی کچھ مل جائے گا جس کی وہ تمنا کرے گا ؟“ یہ آیت گویا مذکورہ سوال کا جواب ہے۔"
}

2. Hadith

Get a hadith by book and hadithNo

import { Hadith, HadithBook } from 'islam.js';
const hadith = new Hadith();
const engHadith =  await hadith.getHadith(HadithBook.AbuDawud, 7)
console.log(engHadith);

//Output
{
   "metadata": {
      "name": "Sunan Abu Dawud",
      "section": "Purification (Kitab Al-Taharah)",
      "sectionDetails": {
        "arabicNumberFirst": 1,
        "arabicNumberLast": 390,
        "hadithNumberFirst": 1,
        "hadithNumberLast": 390
       }
   },
   "hadith": {

        "text": "Narrated Salman al-Farsi: It was said to Salman: Your Prophet teaches you everything, even about excrement. He replied: Yes. He has forbidden us to face the qiblah at the time of easing or urinating, and cleansing with right hand, and cleansing with less than three stones, or cleansing with dung or bone",
        "hadithNumber": 7,
        "arabicNumber": 7,
        "grades": [
            {
                "name": "Al-Albani",
                "grade": "Sahih"
            },
            {
                "name": "Muhammad Muhyi Al-Din Abdul Hamid",
                "grade": "Sahih"
            },
            {
                "name": "Shuaib Al Arnaut",
                "grade": "Sahih"
            },
            {
                "name": "Zubair Ali Zai",
                "grade": "Sahih Muslim (262)"
            }
        ]
   }
}

Get a complete section from a book by sectionNo

By default the language will be English but We can specify a different language as well.

import { Hadith, HadithBook, HadithLangEnum } from 'islam.js';
const hadith = new Hadith();
const section =  await hadith.getSection(HadithBook.Bukhari, 6, HadithLangEnum.Russian);
console.log(section);

//Output
{
   "metadata": {
      "name":"Sahih al Bukhari",
      "section":"Menstrual Periods",
      "sectionDetails":{
            "arabicNumberFirst":294,
            "arabicNumberLast":333,
            "hadithNumberFirst":294,
            "hadithNumberLast":333
       }
   },
   "hadiths":[
        {
            "arabicNumber": 294,
            "grades": [],
            "hadithNumber": 294,
            "reference": { "book": 6, "hadith": 1 },
            "text": "Сообщается, что ‘Аиша, да будет доволен ею Аллах, сказала: «Мы покинули (Медину) с единственной целью совершить хаджж, а в Сарифе, у меня начались месячные. Зайдя ко мне, Посланник Аллаха ﷺ (увидел, что) я плачу, и спросил: “Что с тобой? У тебя начались месячные?” Я ответила: “Да”. Тогда он сказал: “Поистине, это предопределено Аллахом дочерям Адама. Совершай же всё, что совершает паломник, но только не обходи Дом (Каабу)!”»\\n(‘Аиша) сказала: «И Посланник Аллаха ﷺ принёс в жертву коров за своих жён»"
        },
        ...
        ...
        ...
   ]
}

3. Dua & Azkar

Get a random supplication

import { Azkar } from 'islam.js';
const azkar = new Azkar();
const supplication = azkar.getRandom();
console.log(supplication);

//Output
{
   "id":2669,
   "description":{
      
   },
   "count":"",
   "zikr":"((يُصَلِّي عَلَى النَّبِيِّ صلى الله عليه وسلم بَعْدَ فَرَاغِهِ مِنْ إِجَابَةِ الْمُؤَذِّنِ)).",
   "reference":"",
   "category":"أذكار الآذان"
}

Get a random supplication by category

import { Azkar } from 'islam.js';
const azkar = new Azkar();
const supplication = azkar.getRandomByCategory(AzkarCategoriesEnum.Anxiety);
console.log(supplication);

//Output
{
   "id":809,
   "description":{},
   "count":"",
   "zikr":"((اللَّهُمَّ إِنِّي أَعُوذُ بِكَ مِنَ الْهَمِّ وَالْحَزَنِ، وَالْعَجْزِ وَالْ