Skip to content

Calendar widget

What it is

Fetches events from a public iCal/ICS feed and shows them as an agenda list, updated on a regular poll interval.

Config fields

FieldWhat it controlsExample
Calendar URL (iCal/ICS)The .ics URL of the calendar to display. Must be publicly accessible (no auth required).https://calendar.google.com/calendar/ical/…/basic.ics
Days aheadHow many days into the future to show events. Options: 1, 3, 7, 14, 30 days.7
Max eventsMaximum number of events to list. Options: 5, 10, 20, 50.10
Show private eventsHow to handle events marked private: show (full title), mask (replace with the custom label), or hide (omit entirely).mask
Private event labelReplacement text shown when “Show private events” is set to “mask”.Busy
Event colorDefault dot/accent colour for event entries.#3b82f6
Current event colorAccent colour for events that are happening right now.#22c55e
Header backgroundBackground colour for the day-header row. Set to transparent to inherit from the tile.transparent

Getting your iCal URL

Google Calendar

  1. Open Google Calendar → Settings (gear icon) → Settings.
  2. In the left sidebar, click the calendar name under “Settings for my calendars”.
  3. Scroll to Secret address in iCal format and copy the URL. Use the secret address — the public address only contains public events.

Outlook / Microsoft 365

  1. Open Outlook on the web (outlook.office.com).
  2. Click the calendar icon → right-click the calendar → Sharing and permissions.
  3. Choose Publish a calendar, set the permission level, and copy the ICS link.

Apple iCloud

  1. Open iCloud.com → Calendar.
  2. Click the share icon (📡) next to the calendar name.
  3. Enable Public Calendar and copy the link. The link ends in .ics.

Common pitfalls

  • Private Google Calendars require the secret address. The non-secret URL only includes events you’ve explicitly marked as public. If the widget shows fewer events than expected, make sure you used the secret iCal URL.
  • iCal URLs expire or change. Google regenerates the secret address if you click “Reset”. Outlook URLs are invalidated when you stop sharing. Update the widget URL when this happens.
  • All-day multi-day events. Multi-day all-day events (e.g. holidays spanning a week) appear on their start date only.
  • Recurring events. Recurring instances are expanded up to the configured “Days ahead” window. Very high-frequency recurrences (e.g. every 5 minutes) can produce a large list.

Troubleshooting

SymptomTry
No events shownPaste the URL in a browser tab and confirm it downloads an .ics file. Check that the calendar has events within the “Days ahead” window.
”Calendar not found” or fetch errorThe URL may be expired or require authentication. Re-generate and update it.
Events show with wrong timeThe iCal feed uses a different timezone than expected. Check the TZID field in the raw feed.
Private events leakingSwitch “Show private events” to “mask” or “hide”.