Small, fast JavaScript/TypeScript library for looking up Icelandic public holidays, and resolving business days before/after a given day. It also provides info about other commonly observed "special" days such as "Bolludagur", etc.
"Half day" holidays (such as Christmas and New Year's Eve) are marked as such, and can be optionally treated as either "work days" or "non-work days", depending on need.
All day names/descriptions are in Icelandic, but each day has a stable key
prop that can be used when translating its name into other languages.
All returned dates are in the UTC timezone and set to midnight.
npm install fridagar
Contents:
Syntax: getHolidays(year?: number, month?: number): Array<Holiday>
Returns all Icelandic public holidays and commonly celebrated "special" days for a given year — optionally narrowed down to a single month.
import { getHolidays } from "fridagar";
const holidays2018 = getHolidays(2018);
const holidaysInDecember2018 = getHolidays(2018, 12);
// If year is omitted the current year is used
const holidaysThisYear = getHolidays();
const holidaysInDecemberThisYear = getHolidays(undefined, 12);Syntax:
getAlldays(year?: number, month?: number): Array<Holiday | SpecialDay>
Returns all official Icelandic public holidays (non-working days) for a given year — optionally narrowed down to a single month.
import { getAllDays } from "fridagar";
const allDays2018 = getAllDays(2018);
const allDaysInDecember2018 = getAllDays(2018, 12);
// If year is omitted the current year is used
const allDaysThisYear = getAllDays();
const allDaysInDecemberThisYear = getAllDays(undefined, 12);Syntax:
getAllDaysKeyed(year?: number): Record<DayKey, Holiday | SpecialDay>
Returns a keyed object with Icelandic public holidays and commonly celebrated "special" days for a given year. (Defaults to the current year.)
import type { Holiday, SpecialDay } from "fridagar";
import { getAllDaysKeyed } from "fridagar";
const allDays1995 = getAllDaysKeyed(1995);
// Note that the days are correctly typed
const easter95: Holiday = allDays1995.paska;
const ashWed95: SpecialDay = allDays1995.osku;
console.log(easter95.date);
// Logs new Date('1995-04-23')
console.log(easter95.description);
// Logs "Páskadagur"Syntax: getOtherDays(year?: number, month?: number): Array<SpecialDay>
Returns only unofficial, commonly celebrated "special days" (that are still workdays) for a given year — optionally narrowed down to a single month.
import { getOtherDays } from "fridagar";
const otherdays2018 = getOtherDays(2018);
const otherdaysInDecember2018 = getOtherDays(2018, 12);
// If year is omitted the current year is used
const otherdaysThisYear = getOtherDays();
const otherdaysInDecemberThisYear = getOtherDays(undefined, 12);Syntax: isHoliday(date: Date): Holiday | undefined
Checks if a given date is an Icelandic public holiday, and if so, returns its info object.
import { isHoliday } from "fridagar";
const res1 = isHoliday(new Date("2018-12-24"));
console.log(res1);
// Logs the `Holiday` object for Aðfangadagur
const res2 = isHoliday(new Date("2018-12-23"));
console.log(res2);
// Logs `undefined` (as Þorláksmessa is not a holiday.)Syntax: isSpecialDay(date: Date): Holiday | SpecialDay | undefined
Checks if a given date is either an Icelandic public holiday or a commonly celebrated "special" day, and if so, returns its info object.
import { isSpecialDay } from "fridagar";
const res1 = isSpecialDay(new Date("2018-12-24"));
console.log(res1);
// Logs the `Holiday` object for Aðfangadagur
const res2 = isSpecialDay(new Date("2018-12-23"));
console.log(res2);
// Logs the `SpecialDay` object for Þorláksmessa
const res3 = isSpecialDay(new Date("2018-12-19"));
console.log(res3);
// Logs `undefined` (Because Dec. 19th is just a normal day.)Syntax:
workdaysFromDate(days: number, refDate?: Date, includeHalfDays?: boolean): Date
Returns the days-th business-day before/after the reference date.
Defaults to counting half-day holidays as "non-work" days.
import { workdaysFromDate } from "fridagar";
const dec23th2018 = new Date("2018-12-23"); // Thursday
const jan1st2025 = new Date("2024-01-01"); // Tuesday
// Treats Aðfangadagur as a non-work day by default
const secondWorkDay = workdaysFromDate(2, dec23th2018);
// new Date('2021-12-28') // Tuesday
// Optionally treats Aðfangadagur as a work day
const secondWorkDayInclHalfDay = workdaysFromDate(2, dec23th2018, true);
// new Date('2021-12-27') // Monday
// One business days before New Year's day of 2024
const prevDay = workdaysFromDate(-1, jan1st2024);
// new Date('2023-12-29') // FridayIf the refDate is omitted, the current (today) date is used.
const thirdWorkDayFromToday = workdaysFromDate(3);NOTE: The returned date is always set to 00:00:00 UTC.
These are the supported days and their identification keys:
- Nýársdagur (
nyars) - Þrettándinn (
threttand) - Bóndadagur (
bonda) - Bolludagur (
bollu) - Sprengidagur (
sprengi) - Öskudagur (
osku) - Valentínusardagur (
valent) - Konudagur (
konu) - Skírdagur (
skir) - Föstudagurinn langi (
foslangi) - Páskadagur (
paska) - Annar í páskum (
paska2) - Sumardagurinn fyrsti (
sumar1) - Verkalýðsdagurinn (
mai1) - Uppstigningardagur (
uppst) - Hvítasunnudagur (
hvitas) - Annar í Hvítasunnu (
hvitas2) - Sjómannadagurinn (
sjomanna) - Þjóðhátíðardagurinn (
jun17) - Sumarsólstöður (
sumsolst) - Jónsmessa (
jonsm) - Frídagur verslunarmanna (
verslm) - Fyrsti vetrardagur (
vetur1) - Hrekkjavaka (
hrekkja) - Dagur íslenskrar tungu (
isltungu) - Fullveldisdagurinn (
fullv) - Vetrarsólstöður (
vetsolst) - Þorláksmessa (
thorl) - Aðfangadagur (
adfanga) - Jóladagur (
jola) - Annar í Jólum (
jola2) - Gamlársdagur (
gamlars)
What to include is always subjective.
Currently the list focuses on:
- Official public holidays (defined in law)
- Official days of flag-raising ("fánadagar") often to do with national independence history, etc.
- Traditional Icelandic cultural "special days", which are a mixture of centuries old folk-traditions and (Christian) religious culture.
- Days that are actively celebrated despite not fulfilling any of the above criteria. (Like "Hrekkjavaka")
This means "Valentínusardagur" is a bit of an oddball in this list. It's inclusion begs the question why we don't include other similar days such as "Mæðradagurinn", "Feðradagurinn", or even "Singles Day". Or should it be removed?
The "on the fence" category includes:
- Mæðradagurinn & Feðradagurinn
- Kvennafrídagurinn
- Bjórdagurinn
- Beginning/end of Ramadan
- St. Patrick's Day
Example: "Dagur íslenskrar tungu" was first celebrated in 1996. Should
getAllDays(1980) include it or not?
Problem is that many days don't have a definite starting date, they just faded into existence over time. Other days (such as "Mæðradagurinn") have had different dates at different times.
Currently the library does NOT aim for historical accuracy, and will return all "modern day" special days for any year — and completely ignore the fact that "Frídagur verslunarmanna in the year 345 BC" makes absolutely no sense.
An object describing an Icelandic public holiday.
import type { Holiday } from "fridagar";
// Example
const xmasEve2017: Holiday = {
date: new Date("2017-12-24T00:00:00.000Z"),
description: "Aðfangadagur",
key: "adfanga", // stable identifier for this holiday
holiday: true,
halfDay: true,
};NOTE: All dates are set to 00:00:00 UTC
An object describing an Icelandic commonly celebrated "special" day, such as "Bolludagur", etc.
import type { SpecialDay } from "fridagar";
// Example
const sovereignDay2017: SpecialDay = {
date: new Date("2017-12-01T00:00:00.000Z"),
description: "Fullveldisdagurinn",
key: "fullv", // stable identifier for this special day
holiday: false, // not a public holiday
};NOTE: All dates are set to 00:00:00 UTC
String union types of all possible key values for Holiday and
SpecialDay objects. These are mainly useful when translating the day
names/descriptions into other languages.
import type { DayKey, HolidayKey, SpecialDayKey } from "fridagar";
const holidayNamesPolish: Record<HolidayKey, string> = {
nyars: "Nowy Rok",
adfanga: "Wigilia",
jola: "Boże Narodzenie",
// etc...
};
const specialDayNamesPolish: Record<SpecialDayKey, string> = {
bollu: "Dzień Pączka",
sjomanna: "Dzień Marynarza",
// etc...
};
// DayKey is a shorthand union of HolidayKey and SpecialDayKey
const allDayNamesPolish: Record<DayKey, string> = {
...holidayNamesPolish,
...specialDayNamesPolish,
};This project uses the Bun runtime for development (tests, build, etc.)
PRs are welcoms!
See CHANGELOG.md
is-kennitala- Best-of-breed kennitala (Icelandic national ID) validation and utility library.postnumer- Icelandic post-codes (Póstnúmer) and town/locality names and their National Registry ID codes.