====== User Manual ======

**PrayTime** is a lightweight and flexible JavaScript library for calculating prayer times.

This manual provides a guide on how to use the library in web pages and JavaScript-based applications.

===== Download =====

  * [[https://praytime.info/code/praytime/src/praytime.js|praytime.js]] (v3.1) [‌[[https://praytime.info/code/praytime/dist/praytime.min.js|5KB minified]]]
  * Get from [[https://github.com/zarrabi/praytime|GitHub]] or [[https://www.npmjs.com/package/praytime|npm]]
  * See [[ChangeLog|changes log]]

===== Examples =====

  * A simple example: [[https://praytime.info/code/praytime/examples/daily.html|daily.html]]
  * Monthly timetable: [[https://praytime.info/code/praytime/examples/monthly.html|monthly.html]]
  * Yearly prayer times: [[https://praytime.info/code/praytime/examples/yearly.html|yearly.html]]


===== Using PrayTime =====

PrayTime is designed to work both in browser and in Node.js.

==== Browser ====

<code html>
<script src="praytime.js"></script>
<script>
    const praytime = new PrayTime();
    praytime.times();
</script>
</code>

You can also load the js file directly from a [[https://www.jsdelivr.com/package/npm/praytime|CDN]].

==== Node.js ====

<code bash>
npm install praytime
</code>

<code javascript>
const { PrayTime } = require('praytime');

const praytime = new PrayTime();
praytime.times();
</code>

The output of ''praytime.times()'' in both examples above is a JavaScript object with the following structure:

<code>
{
  fajr: '05:03',
  sunrise: '06:21',
  dhuhr: '12:27',
  asr: '15:53',
  sunset: '18:34',
  maghrib: '18:35',
  isha: '19:52',
  midnight: '00:27'
}
</code>

The PrayTime library offers a range of functions to customize calculation parameters, as detailed below. To test the sample code snippets, simply open your browser's console and execute them.

===== Set Calculation Method =====

The default calculation method used in PrayTime is Muslim World League (MWL). You can change the calculation method using the following function:

  method(method)

The ''method'' parameter is a string that can be set to any of the followings:

^Method ^Description                                  ^
|MWL    |Muslim World League                          |
|ISNA   |Islamic Society of North America             |
|Egypt  |Egyptian General Authority of Survey         |
|Makkah |Umm al-Qura University, Makkah               |
|Karachi|University of Islamic Sciences, Karachi      |
|Tehran |Institute of Geophysics, University of Tehran|
|Jafari |Leva Research Institute, Qom                 |
|France |Muslims of France                            |
|Russia |Spiritual Administration of Muslims of Russia|
|Singapore |Islamic Religious Council of Singapore    |


More information on the above calculation methods is provided [[methods|here]]. You can also [[#Add New Calculation Methods|add dew calculation methods]] to the library if needed.

**Example**

<code javascript>
praytime.method('ISNA');
</code>

**Note**: You can set the calculation method upon initializing the praytime object.

<code javascript>
const praytime = new PrayTime('ISNA');
</code>

===== Set Location =====

The following function is used to set location:

  location(coordinates)

The **coordinates** should be provided as an array ''[latitude, longitude]''. The latitude is a real number between -90 and 90, while the longitude ranges from -180 to 180.

**Example**

<code javascript>
praytime.location([43, -80]);
</code>

===== Set Timezone =====

To set timezone, we can use the following function:

  utcOffset(utcOffset)

The **utcOffset** parameter is a real number representing the difference from Greenwich Mean Time (GMT) in hours or minutes. If not provided or set to 'auto', the ''utcOffset'' is automatically determined based on the system's time settings.

For time zones like +3:30, the utcOffset parameter can be entered as 3.5. For daylight saving time, simply add 1 to the utcOffset.

**Example**

<code javascript>
praytime.utcOffset(-5);
</code>

**Note**: It is recommended to use a modern library such as [[https://moment.github.io/luxon/|luxon]] for dealing with timezones. 


===== Get Prayer Times =====

To retrieve prayer times, use the following function:  

  times(date)

The **date** parameter can be in any of the following types:  

^Type ^Description   ^Example^                               
|date    |A JavaScript ''Date'' object | ''new Date()''                         |
|array   |An array [year, month, day] | ''[2025, 3, 21]'' (for March 21, 2025)           |
|timestamp |Unix timestamp in milliseconds | 1742686502920  |
|number |Day offset from current date (< 1000) | 7 (for next week)      |

If no date is provided, the function defaults to the system's current date.

The output of ''times'' function is an object containing 8 prayer times (see [[calculation| here]] for the list of times and their definition). Each time can be accessed through its name. For example, if the output of ''times'' function is stored in an object ''times'', the time for sunrise can be accessed through ''times.sunrise''.

**Example**

<code javascript>
const times = praytime.times()
console.log('Sunset : ' + times.sunset)
</code>


**Note**: PrayTime has a //chainable API//, allowing you to set multiple parameters at once, before calling the final times method. An example is provided below.

<code javascript>
praytime.method('ISNA').location([43, -80]).utcOffset(-5).times();
</code>

===== Formatting Output =====

the returned prayer times are formatted as a 24-hour string by default.
To customize the time format, you can use the following function:

  format(format)

The **format** parameter can be any of the followings:
^Format^Description                    ^Example^
|24h   |24-hour time format            |18:35  |
|12h   |12-hour time format            |6:35   |
|12H   |12-hour time format with suffix|6:35 PM|
|x     |Unix timestamp in milliseconds |1742686502920 |
|X     |Unix timestamp in seconds      |1742686502 |

**Example**

<code javascript>
praytime.format('12h').times()
</code>

===== Adjusting Parameters =====

The calculating parameters can be adjusted using the following function:

  adjust(parameters)

''parameters'' is an object composed of any number of the following parameters:

^Parameter^Values                                ^Description                             ^Sample Value^
|fajr     |degrees                               |twilight angle                          |15          |
|dhuhr    |minutes                               |minutes after mid-day                   |1 min       |
|asr      |method                                |asr juristic method; see the table below|Standard    |
|   :::   |factor   |shadow length factor for realizing asr|1.7                                        |
|maghrib  |degrees                               |twilight angle                          |4           |
|   :::   |minutes  |minutes after sunset                  |15 min                                     |
|isha     |degrees                               |twilight angle                          |18          |
|   :::   |minutes  |minutes after maghrib                 |90 min                                     |
|midnight |method                                |midnight method; see the table below    |Standard    |
|highLats |method                                |higher latitudes adjustment; see below  |None        |

==== Asr methods ====

^Method  ^Description ([[Calculation#Asr|more info]])           ^
|Standard|Shafii, Maliki, Jafari and Hanbali (shadow factor = 1)|
|Hanafi  |Hanafi school of tought (shadow factor = 2)           |

==== Midnight methods ====

^Method  ^Description                         ^
|Standard|The mean time from Sunset to Sunrise|
|Jafari  |The mean time from Maghrib to Fajr  |

==== Higher latitudes methods ==== 

^Method     ^Description ([[Calculation#Higher_Latitudes|more info]])^
|None       |No adjustments                                          |
|NightMiddle|The middle of the night method                          |
|OneSeventh |The 1/7th of the night method                           |
|AngleBased |The angle-based method (recommended)                    |

**Example**

<code javascript>
praytime.adjust( {fajr: 16, dhuhr: '5 min', asr: 'Hanafi', isha: 15} );
</code>

===== Tuning Times =====

You can further tune calculated prayer times (for precaution) using the following function:

  tune(offsets)

where ''offsets'' is an associative array containing time offsets in minutes for each prayer time.

**Example**

<code javascript>
praytime.tune( {sunrise: -1, sunset: 3.5} );
</code>

===== Rounding Times =====

By default, PrayTime rounds minutes to the nearest values. To round the times in different way, you can use the following function. 

  round(method)

where ''method'' parameter can be any of the followings:

^Method   ^Description ^
|up       |Round minutes up (ceil)           |
|down     |Round minutes down (floor)        |
|nearest  |Round to the nearest minute       |
|none     |No rounding                       |

**Example**

<code javascript>
praytime.round('up');
</code>


===== Advanced Topics =====


==== Get List of Calculation Methods ====

You can get the list of calculation methods available in PrayTime via ''praytime.methods'' object.

<code javascript>
console.log(praytime.methods);
</code>

The output will be as follows.
<code javascript>
{
  MWL: { fajr: 18, isha: 17 },
  ISNA: { fajr: 15, isha: 15 },
  Egypt: { fajr: 19.5, isha: 17.5 },
  Makkah: { fajr: 18.5, isha: '90 min' },
  Karachi: { fajr: 18, isha: 18 },
  Tehran: { fajr: 17.7, maghrib: 4.5, midnight: 'Jafari' },
  Jafari: { fajr: 16, maghrib: 4, midnight: 'Jafari' },
  defaults: { isha: 14, maghrib: '1 min', midnight: 'Standard' }
}
</code>

Note that ''defaults'' parameters are applied to all methods.

==== Add New Calculation Methods ====

You can add new calculation methods to the list of calculation methods available in PrayTime as follows.

<code javascript>
praytime.methods['France'] = { fajr: 12, isha: 12 };
praytime.methods['Singapore'] = { fajr: 20, isha: 18 };
</code>

You can then use the new calculation methods like other methods available in PrayTime:
<code javascript>
praytime.method('France');
</code>


===== Related Links =====

  * [[calculation|How are prayer times determined?]]
  * [[code|See all versions of PrayTime code]]