Google Calendar Week Number Display

WHAT IT DOES

This script adds week numbers to Google Calendar, making it easy to reference weeks by number in both month and week views. In month view, week numbers appear as a left-hand column next to each week row, showing the ISO week number (or US week number) for that week. In week view, each week row displays a small badge with the week number. The week numbers update automatically as you navigate between weeks and months, and you can choose between ISO 8601 week numbering (where week 1 starts on Monday and always contains January 4) or US week numbering (where week 1 starts on January 1). This is especially useful for project planning, sprint tracking, academic scheduling, and any context where weeks are referenced by number rather than by date range.

WHERE IT RUNS

The script runs on all Google Calendar domains (*.calendar.google.com). It works in month view, week view, and day view (with week context). It supports both desktop and mobile views.

HOW TO USE

After installation, the settings panel appears on the left side of the screen with the gear emoji (⚙️). Open the panel to configure the script:

- The "Show week numbers" toggle enables or disables the week number display.

- Select the numbering system from the dropdown: "ISO 8601 (Monday as first day)" or "US (Sunday as first day)."

- Click "Refresh calendar" to manually reapply week numbers if they don't appear.

- Click "Reset" to restore default settings.

The week numbers appear automatically when you open Google Calendar. They update when you navigate between weeks, months, or days.

TECHNICAL SECTION — REAL MECHANISM

The script detects Google Calendar pages by checking the URL for calendar.google.com. It determines the current calendar view by parsing the URL parameters (view=month, view=week, view=day) or by detecting DOM elements like .monthgrid, .weekgrid, or .IuEBg. The current date is extracted from the URL's date parameter (format YYYYMMDD) or from the datepicker element's text. For each week row in the calendar grid, the script extracts the first date of that row by scanning cells for data-date or data-timestamp attributes, or by parsing the day number from cell text and determining the month/year from the context. The ISO week number is calculated using the standard algorithm: get the Thursday of the week, then calculate the number of weeks since the first week of the year. The US week number is calculated as the number of days since January 1 divided by 7, plus 1. Week numbers are displayed by inserting a badge or column element into each row using style properties and textContent (never innerHTML). The script uses a MutationObserver to watch for DOM changes and re-display week numbers when the calendar navigates. Click events on calendar navigation buttons are also monitored to trigger updates.

THE PANEL

The settings panel is built with BotGentz's BGPanel component. It is draggable via its header, allowing you to reposition it anywhere on the screen. The panel snaps to the left edge by default but can be moved freely. Click the gear emoji to collapse the panel into a small bubble, and click the bubble to expand it again. The panel remembers its position per page session. Press the Escape key to quickly close or minimize the panel. The panel includes a status flash bar that provides visual feedback when settings are changed or actions are performed. All settings save automatically via GM_setValue.

PLEASE NOTE

This script requires the free BotGentz browser extension to run. It does not function as a standalone Chrome extension and does not use chrome.* APIs. Google Calendar frequently updates its interface, which may break the selectors used to find week rows and dates. If week numbers stop appearing, please check for script updates. The ISO week numbering standard defines week 1 as the week containing January 4. The US week numbering defines week 1 as the week starting with January 1. The script stores only your enabled state and numbering system preference via GM_setValue. No data is sent externally—all data is stored locally in your browser. The script never reads or writes password fields, hidden inputs, or file inputs. All DOM operations use safe methods (style properties, textContent, appendChild) and never use innerHTML.