First day of week from HTML5 Intl API

Question

Is there a way to get the first day of the week (Sunday or Monday for most countries) from the HTML5 internationalization API?

The spec can be found here. I would be surprised if it's not somehow disclosed, but I can't seem to find where.

Answer 1

The official vanilla API for retrieving this is Locale.prototype.getWeekInfo(), or the currently more supported Locale.prototype.weekInfo (Firefox does not support either!):

Small note: Firefox does not support either!

// New API, currently only in Deno, Bun & Safari Technology Preview (2023-10)
new Intl.Locale('en-US').getWeekInfo()

// "Old" API, available in Chrome, Edge, Opera, Node & other Chromium-based browsers
new Intl.Locale('en-US').weekInfo

which will return an object like:

{
    firstDay: 7,      // First day of the week is Sunday
    minimalDays: 1,   // First calendar week of the year must have at least 1 weekday
    weekend: [6, 7]   // Weekend is Saturday and Sunday
}

---

Examples for other cultures: (new Intl.Locale('<locale>').weekInfo)

Germany de-DE:

{
    firstDay: 1,      // First day of the week is Monday
    minimalDays: 4,   // First calendar week of the year has at least 4 weekdays
    weekend: [6, 7]   // Weekend is Saturday and Sunday
}

Egypt ar-EG:

{
    firstDay: 6,      // First day of the week is Saturday
    minimalDays: 1,   // First calendar week of the year has at least 1 weekday
    weekend: [5, 6]   // Weekend is Friday and Saturday
}

Uganda sw-UG:

{
    firstDay: 1,      // First day of the week is Monday
    minimalDays: 1,   // First calendar week of the year has at least 1 weekday
    weekend: [7]      // Weekend is Sunday only
}

Brunei ms-BN:

{
    firstDay: 7,      // First day of the week is Sunday
    minimalDays: 1,   // First calendar week of the year has at least 1 weekday
    weekend: [5, 7]   // Weekend is Friday and Sunday
}

---

Polyfilling this is possible, but I recommend the excellent date-fns library until the Temporal API arrives in most browsers, which has similar data (without weekend information) available for currently 93 locales:

import { enUS, deAT, ar, hi } from 'date-fns/locale'

enUS.options.weekStartsOn          // 0 <- careful, 0 = Sunday
enUS.options.firstWeekContainsDate // 1

deAT.options.weekStartsOn          // 1
deAT.options.firstWeekContainsDate // 4

// Arabic
ar.options.weekStartsOn            // 6
ar.options.firstWeekContainsDate   // 1

// Hindi
hi.options.weekStartsOn            // 0
hi.options.firstWeekContainsDate   // 4

---

Small Note - the spec has changed from a property to a function, since all browsers/runtimes implemented weekInfo as a getter which would always return a new object, and cause this unintuitive behavior:

const swedish = new Intl.Locale('sv');
swedish.weekInfo === swedish.weekInfo  // false