@hebcal/core
    Preparing search index...

    Class HebrewCalendar

    HebrewCalendar is the main interface to the @hebcal/core library. This namespace is used to calculate holidays, rosh chodesh, candle lighting & havdalah times, Parashat HaShavua, Daf Yomi, days of the omer, and the molad. Event names can be rendered in several languges using the locale option.

    Index
    calendar eruvTavshilin getBirthdayOrAnniversary getHolidaysForYear getHolidaysForYearArray getHolidaysOnDate getSedra getYahrzeit hallel reformatTimeStr tachanun version

    • Calculates holidays and other Hebrew calendar events based on CalOptions.

      Each holiday is represented by an Event object which includes a date, a description, flags and optional attributes. If given no options, returns holidays for the Diaspora for the current Gregorian year.

      This is a convenience wrapper around the standalone calendar function. See calendar for the complete list of supported options, the candle-lighting and Havdalah defaults, and notes on locales.

      Parameters

      Returns Event[]

      import {HebrewCalendar, Location} from '@hebcal/core';
      const options: CalOptions = {
        year: 1981,
        isHebrewYear: false,
        candlelighting: true,
        location: Location.lookup('San Francisco'),
        sedrot: true,
        omer: true,
      };
      const events = HebrewCalendar.calendar(options);
      for (const ev of events) {
        const hd = ev.getDate();
        const date = hd.greg();
        console.log(date.toLocaleDateString(), ev.render('en'), hd.toString());
      }

    • Returns true if Eruv Tavshilin should be prepared on the given date.

      Eruv Tavshilin is prepared when a Yom Tov falls on Friday (so cooking for Shabbat that begins Friday night may continue from Yom Tov into Shabbat). This requires the day before to be a weekday (Wednesday or Thursday), the following Friday to be Yom Tov, and the day after Friday (Shabbat) to also be a sacred day.

      Parameters

      • date: HDate | Date

        Gregorian or Hebrew date to test

      • il: boolean

        use the Israeli holiday schedule

      Returns boolean

      import {HebrewCalendar} from '@hebcal/core';
      // Wednesday October 16, 2024 is Erev Sukkot 5785. In the Diaspora,
      // Sukkot I falls on Thursday and Sukkot II on Friday, so Eruv
      // Tavshilin is prepared on Wednesday:
      HebrewCalendar.eruvTavshilin(new Date(2024, 9, 16), false); // true
      // In Israel there is only one day of Yom Tov, so Friday is a weekday:
      HebrewCalendar.eruvTavshilin(new Date(2024, 9, 16), true); // false

    • Calculates a birthday or anniversary (non-yahrzeit). Returns undefined when hyear precedes the original year of gdate.

      When hyear is the original year, the original date is returned unchanged — a "0th birthday" is a meaningful thing to ask for. This differs from getYahrzeit, which returns undefined for the original year, because a yahrzeit only has meaning from the first anniversary onward.

      Hebcal uses the algorithm defined in "Calendrical Calculations" by Edward M. Reingold and Nachum Dershowitz.

      The birthday of someone born in Adar of an ordinary year or Adar II of a leap year is also always in the last month of the year, be that Adar or Adar II. The birthday in an ordinary year of someone born during the first 29 days of Adar I in a leap year is on the corresponding day of Adar; in a leap year, the birthday occurs in Adar I, as expected.

      Someone born on the thirtieth day of Marcheshvan, Kislev, or Adar I has his birthday postponed until the first of the following month in years where that day does not occur. [Calendrical Calculations p. 111]

      Parameters

      • hyear: number

        Hebrew year

      • gdate: HDate | Date

        Gregorian or Hebrew date of event

      Returns HDate | undefined

      anniversary occurring in hyear

      import {HebrewCalendar} from '@hebcal/core';
      const dt = new Date(2014, 2, 2); // '2014-03-02' == '30 Adar I 5774'
      const hd = HebrewCalendar.getBirthdayOrAnniversary(5780, dt); // '1 Nisan 5780'
      console.log(hd.greg().toLocaleDateString('en-US')); // '3/26/2020'

    • Lower-level holidays interface, which returns a Map of Events indexed by HDate.toString(). These events must be filtered for flags.IL_ONLY or flags.CHUL_ONLY depending on Israel vs. Diaspora holiday scheme.

      Includes Rosh Chodesh, fasts, Yom Kippur Katan, Special Shabbatot, etc., but does not generate candle-lighting times, Torah readings, or Omer days. The result is cached in an internal LRU.

      Parameters

      • year: number

        Hebrew year

      Returns HolidayYearMap

      import {HebrewCalendar} from '@hebcal/core';
      const map = HebrewCalendar.getHolidaysForYear(5784);
      for (const [hdStr, events] of map.entries()) {
        for (const ev of events) {
          console.log(hdStr, ev.getDesc());
        }
      }

    • Returns a sorted array of holidays observed during the given Hebrew year.

      Events are pre-filtered by Israel vs. Diaspora schedule, so callers do not need to inspect flags.IL_ONLY / flags.CHUL_ONLY themselves. Includes Rosh Chodesh, fasts, modern holidays, special Shabbatot, etc., but does not generate candle-lighting times, Torah readings, or Omer days.

      Parameters

      • year: number

        Hebrew year

      • il: boolean

        use the Israeli schedule for holidays

      Returns HolidayEvent[]

      import {HebrewCalendar} from '@hebcal/core';
      const events = HebrewCalendar.getHolidaysForYearArray(5784, false);
      console.log(events[0].getDesc()); // 'Rosh Hashana 5784'

    • Returns an array of holiday Events that occur on the given date, or undefined if no holidays occur that day.

      When il is omitted, both Diaspora-only and Israel-only events are returned; pass true or false to filter to a single schedule.

      Parameters

      • date: number | HDate | Date

        Hebrew Date, Gregorian date, or absolute R.D. day number

      • Optionalil: boolean

        use the Israeli schedule for holidays

      Returns HolidayEvent[] | undefined

      import {HebrewCalendar, HDate, months} from '@hebcal/core';
      const hd = new HDate(15, months.NISAN, 5784);
      const events = HebrewCalendar.getHolidaysOnDate(hd, false);
      console.log(events?.map(ev => ev.getDesc())); // ['Pesach I']

    • Convenience function to create an instance of Sedra or reuse a previously created and cached instance for the same year + schedule.

      Use this in preference to new Sedra(...) when calling repeatedly, since an internal LRU cache (~120 entries) avoids recomputing the keviyah-specific reading pattern.

      Parameters

      • hyear: number

        Hebrew year

      • il: boolean

        Use Israel sedra schedule (false for Diaspora)

      Returns Sedra

      import {HebrewCalendar, HDate} from '@hebcal/core';
      const sedra = HebrewCalendar.getSedra(5784, false);
      const result = sedra.lookup(new HDate(15, 'Cheshvan', 5784));
      console.log(result.parsha); // ['Vayera']

    • Calculates yahrzeit. hyear must be after original gdate of death. Returns undefined when requested year preceeds or is same as original year.

      Hebcal uses the algorithm defined in "Calendrical Calculations" by Edward M. Reingold and Nachum Dershowitz.

      The customary anniversary date of a death is more complicated and depends also on the character of the year in which the first anniversary occurs. There are several cases:

      • If the date of death is Marcheshvan 30, the anniversary in general depends on the first anniversary; if that first anniversary was not Marcheshvan 30, use the day before Kislev 1.
      • If the date of death is Kislev 30, the anniversary in general again depends on the first anniversary — if that was not Kislev 30, use the day before Tevet 1.
      • If the date of death is Adar II, the anniversary is the same day in the last month of the Hebrew year (Adar or Adar II).
      • If the date of death is Adar I 30, the anniversary in a Hebrew year that is not a leap year (in which Adar only has 29 days) is the last day in Shevat.
      • In all other cases, use the normal (that is, same month number) anniversary of the date of death. [Calendrical Calculations p. 113]

      Parameters

      • hyear: number

        Hebrew year

      • gdate: HDate | Date

        Gregorian or Hebrew date of death

      Returns HDate | undefined

      anniversary occurring in hyear

      import {HebrewCalendar} from '@hebcal/core';
      const dt = new Date(2014, 2, 2); // '2014-03-02' == '30 Adar I 5774'
      const hd = HebrewCalendar.getYahrzeit(5780, dt); // '30 Sh\'vat 5780'
      console.log(hd.greg().toLocaleDateString('en-US')); // '2/25/2020'

    • Determines which form of Hallel (if any) is recited on a given Hebrew date.

      Returns 0 (none), 1 (half Hallel), or 2 (whole Hallel).

      Whole Hallel is said on Chanukah, the first Yom Tov of Pesach, Shavuot, Sukkot, Yom Ha'atzmaut, and Yom Yerushalayim.

      Half Hallel is said on Rosh Chodesh (not Rosh Hashanah), and the last 6 days of Pesach.

      Parameters

      • hdate: HDate

        Hebrew date to test

      • il: boolean

        use the Israeli holiday schedule

      Returns number

      0 for no Hallel, 1 for half Hallel, 2 for whole Hallel

      import {HebrewCalendar, HDate, months} from '@hebcal/core';
      HebrewCalendar.hallel(new HDate(25, months.KISLEV, 5784), false); // 2 (Chanukah)
      HebrewCalendar.hallel(new HDate(1, months.SHVAT, 5784), false);   // 1 (Rosh Chodesh)
      HebrewCalendar.hallel(new HDate(2, months.SHVAT, 5784), false);   // 0

    • Helper function to format a 24-hour (00:00-23:59) time string in either 12-hour US format (e.g. "8:13pm") or keep it in 24-hour format (e.g. "20:13") for any other locale or country.

      The locale (and therefore default behavior) is derived from options.location / options.locale. The options.hour12 override takes precedence: if false, locale is ignored and the result is always 24-hour; if true, locale is ignored and the result is always 12-hour.

      Parameters

      • timeStr: string

        original time like "20:30"

      • suffix: string

        "p" or "pm" or " P.M.". Add leading space if you want it

      • Optionaloptions: CalOptions

        optional; location, locale and hour12 are consulted

      Returns string

      import {HebrewCalendar, Location} from '@hebcal/core';
      const opts = {location: Location.lookup('Chicago')};
      HebrewCalendar.reformatTimeStr('20:30', 'pm', opts);          // '8:30pm'
      HebrewCalendar.reformatTimeStr('20:30', 'pm', {hour12: false}); // '20:30'

    • Return details on what Tachanun (or Tzidchatcha on Shabbat) is said on hdate.

      Tachanun is not said on Rosh Chodesh, the month of Nisan, Lag Baomer, Rosh Chodesh Sivan until Isru Chag, Tisha B'av, 15 Av, Erev Rosh Hashanah, Rosh Hashanah, Erev Yom Kippur until after Simchat Torah, Chanukah, Tu B'shvat, Purim and Shushan Purim, and Purim and Shushan Purim Katan.

      In some congregations Tachanun is not said until from Rosh Chodesh Sivan until 14th Sivan, Sukkot until after Rosh Chodesh Cheshvan, Pesach Sheini, Yom Ha'atzmaut, and Yom Yerushalayim.

      Tachanun is not said at Mincha on days before it is not said at Shacharit.

      Tachanun is not said at Shacharit on Shabbat, but is at Mincha, usually.

      Parameters

      • hdate: HDate

        Hebrew date to test

      • il: boolean

        use the Israeli holiday schedule

      Returns TachanunResult

      import {HebrewCalendar, HDate, months} from '@hebcal/core';
      // Regular weekday — Tachanun is said at both services
      HebrewCalendar.tachanun(new HDate(4, months.SHVAT, 5784), false);
      // => { shacharit: true, mincha: true, allCongs: true }

      // Friday 2 Sh'vat — said at Shacharit, but not at Mincha (erev Shabbat)
      HebrewCalendar.tachanun(new HDate(2, months.SHVAT, 5784), false);
      // => { shacharit: true, mincha: false, allCongs: true }

      // Rosh Chodesh — no Tachanun
      HebrewCalendar.tachanun(new HDate(1, months.SHVAT, 5784), false);
      // => { shacharit: false, mincha: false, allCongs: false }

    • Returns the semantic version string of the @hebcal/core package (e.g. "6.8.2"). Useful for logging or feature detection.

      Returns string

    Settings
    Member Visibility

    On This Page
    Methods