JavaScript Calendar Widget: Build or Embed One on Any Page
By SimpleCalendarJS Team
A JavaScript calendar widget is a small, self-contained calendar you add to a page with one container and one script. For a basic month grid, about 60 lines of vanilla JS with Intl is enough. Use an inline picker like flatpickr for choosing dates, and a component like SimpleCalendarJS when the widget has to show events.
You need a calendar on a page that isn't really "about" the calendar: a sidebar showing upcoming events, a small month view on a club homepage, an inline date picker in a booking form. A JavaScript calendar widget is the usual answer, but the term covers three different things, and the right tool depends on which one you need. This guide covers all three, with working code: a dependency-free mini calendar you can paste in, inline picker libraries, and an event widget with a drop-in embed script you can reuse across sites.
What Counts as a JavaScript Calendar Widget
A widget is different from a full calendar app in three ways:
- It's compact. It sits in a sidebar, a card or a form, often 250–400 px wide, not across the whole viewport.
- It's self-contained. One container element and one script. No routing and no app shell, and it shouldn't depend on the page's framework.
- It's embeddable. You often need to drop it into pages you don't fully control: a CMS template, a landing page builder, a client's WordPress site.
Within that, widgets do one of three jobs:
- Show the date. A mini month grid with today highlighted and maybe a few marked days.
- Pick a date or range. An inline date picker that's always visible instead of popping up from an input.
- Show events. An "upcoming events" list or a small month view with event entries, loaded from a feed.
Choose your tool by the job, not by the word "widget".
Ways to Add a Calendar Widget Compared
| Approach | Best for | Size / dependencies | Styling control | License |
|---|---|---|---|---|
| Google Calendar iframe embed | Showing a public Google Calendar as-is | No JS on your side | Only through Google's embed options; your CSS can't reach inside the iframe | Free with a Google account |
| Hand-rolled vanilla JS | Mini month grid, marked days | ~60 lines, zero dependencies | Full | Yours |
flatpickr (inline: true) | Inline date and range picking | Zero runtime dependencies | Themes plus CSS | MIT |
| Vanilla Calendar Pro | Inline date, multi-date and range picking, TypeScript projects | Zero dependencies | CSS themes | MIT |
| SimpleCalendarJS | Event widgets (list, month, week, day) plus date/range picker | ~14 KB gzipped JS, zero dependencies | CSS custom properties | Free for personal, educational and open source use; commercial license required otherwise |
A few details matter here:
- The Google embed isn't small. Google's help page says the embed's width and height must each be at least 500, and the calendar has to be public for visitors to see it. That makes it a poor fit for a sidebar. If you want Google data in your own widget, see how to add Google Calendar events to your website.
- flatpickr's
inlineoption (Boolean, defaultfalse) keeps the calendar always visible instead of opening as a popup. As of November 2026 the latest npm release is 4.6.13, with no runtime dependencies. - Vanilla Calendar Pro is at 3.4.0 on npm as of November 2026. It's MIT-licensed, has zero dependencies and ships TypeScript definitions. It's a strong choice when the widget's job is picking dates.
Neither picker library is built to display events with times and titles. That's where an event calendar component fits.
Building a Minimal JavaScript Calendar Widget From Scratch
If all you need is a month grid with today highlighted and a few marked days, you don't need a library. Intl.DateTimeFormat handles month and weekday names in any locale, and Date handles the arithmetic.
The widget below has previous/next navigation, a configurable week start, locale-aware labels and marked days. It also sends a dateclick event that the rest of your page can listen for.
<div id="mini-cal" class="mini-cal"></div> <style> .mini-cal { max-width: 300px; font: 14px/1.4 system-ui, sans-serif; } .mini-cal header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px; } .mini-cal header button { border: 0; background: none; font-size: 18px; cursor: pointer; padding: 4px 10px; } .mini-cal table { width: 100%; border-collapse: collapse; table-layout: fixed; } .mini-cal th { font-weight: 600; color: #6b7280; padding: 4px 0; } .mini-cal td { text-align: center; padding: 2px; } .mini-cal td button { width: 100%; aspect-ratio: 1; border: 0; border-radius: 50%; background: none; cursor: pointer; position: relative; } .mini-cal td button:hover { background: #f3f4f6; } .mini-cal td button.today { background: #4f46e5; color: #fff; } .mini-cal td button.marked::after { content: ''; position: absolute; bottom: 3px; left: 50%; width: 4px; height: 4px; margin-left: -2px; border-radius: 50%; background: currentColor; } </style> <script> function miniCalendar(root, { locale = navigator.language, weekStartsOn = 1, marked = [] } = {}) { const view = new Date(); view.setDate(1); const markedSet = new Set(marked); const pad = (n) => String(n).padStart(2, '0'); const key = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`; const titleFmt = new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' }); const weekdayFmt = new Intl.DateTimeFormat(locale, { weekday: 'narrow' }); function render() { const year = view.getFullYear(); const month = view.getMonth(); const offset = (new Date(year, month, 1).getDay() - weekStartsOn + 7) % 7; const daysInMonth = new Date(year, month + 1, 0).getDate(); const todayKey = key(new Date()); // 4 January 2026 is a Sunday, so 4 + n gives weekday n (0 = Sunday) let head = ''; for (let i = 0; i < 7; i++) { const weekday = (i + weekStartsOn) % 7; head += `<th scope="col">${weekdayFmt.format(new Date(2026, 0, 4 + weekday))}</th>`; } let cells = '<tr>' + '<td></td>'.repeat(offset); for (let d = 1; d <= daysInMonth; d++) { const k = key(new Date(year, month, d)); const cls = [k === todayKey && 'today', markedSet.has(k) && 'marked'].filter(Boolean).join(' '); cells += `<td><button type="button" class="${cls}" data-date="${k}">${d}</button></td>`; if ((offset + d) % 7 === 0 && d !== daysInMonth) cells += '</tr><tr>'; } cells += '</tr>'; root.innerHTML = ``; } root.addEventListener('click', (e) => { const nav = e.target.closest('[data-nav]'); if (nav) { view.setMonth(view.getMonth() + Number(nav.dataset.nav)); render(); return; } const day = e.target.closest('[data-date]'); if (day) { const [y, m, d] = day.dataset.date.split('-').map(Number); root.dispatchEvent(new CustomEvent('dateclick', { detail: new Date(y, m - 1, d) })); } }); render(); } const cal = document.getElementById('mini-cal'); miniCalendar(cal, { weekStartsOn: 1, marked: ['2026-11-20', '2026-11-27'] }); cal.addEventListener('dateclick', (e) => console.log('Picked', e.detail.toDateString())); </script>
Some details worth copying even if you write your own:
- Keys are built from local date parts (
getFullYear,getMonth,getDate), nottoISOString().toISOString()converts to UTC, which shifts the date by a day for users far enough from UTC. view.setDate(1)comes before any month arithmetic. CallingsetMonth(+1)on 31 January gives 3 March, because 31 February rolls over.- The previous and next buttons have
aria-labels, and the month title is in anaria-liveregion, so screen readers announce the change.
That's about where a hand-rolled widget should stop. Once you need timed events, overlapping entries, a list view, drag and drop or 30 locales of toolbar labels, you're maintaining a calendar library.
Need a calendar in your app?
SimpleCalendarJS: ~14 KB gzipped, zero dependencies, works in any framework. Free for personal use.
Building a JavaScript Calendar Widget With SimpleCalendarJS
SimpleCalendarJS fits the third job, showing events in a compact space. It also covers the second job with its date-picker and range-picker modes. It's a single UMD file with no dependencies, so you can load it with a <script> tag on any page, whether or not the page uses a framework or bundler.
What it doesn't do matters for widgets: there are no recurring events (expand them before returning them), no timezone option (events display in the browser's local time) and no built-in event forms. For a read-only "what's on" widget, none of those usually matters.
A compact "upcoming events" widget
A list view reads better than a month grid in a narrow sidebar. This widget opens on the list, allows switching to month and loads events from a static JSON file:
<link rel="stylesheet" href="https://unpkg.com/simple-calendar-js/dist/simple-calendar-js.min.css"> <script src="https://unpkg.com/simple-calendar-js/dist/simple-calendar-js.min.js"></script> <style> #events-widget .uc-calendar { --cal-font-size: 13px; --cal-primary: #0f766e; --cal-radius: 6px; --cal-event-border-radius: 4px; } </style> <aside style="max-width: 360px"> <h2>What's on</h2> <div id="events-widget" style="height: 420px"></div> </aside> <script> const widget = new SimpleCalendarJs('#events-widget', { defaultView: 'list', enabledViews: ['list', 'month'], listDaysForward: 60, weekStartsOn: 1, weekdayFormat: 'narrow', showYearPicker: false, showTodayButton: false, fetchEvents: async (start, end) => { const res = await fetch('/events.json'); const events = await res.json(); return events .map((e) => ({ ...e, start: new Date(e.start), end: new Date(e.end) })) .filter((e) => e.end >= start && e.start <= end); }, onEventClick: (event) => { if (event.url) window.location.href = event.url; } }); </script>
And events.json, using local date-time strings so nothing shifts across time zones:
[ { "id": 1, "title": "Open evening", "start": "2026-11-20T18:00", "end": "2026-11-20T20:00", "color": "#0f766e", "description": "Main hall, free entry", "url": "/events/open-evening" }, { "id": 2, "title": "Winter fair", "start": "2026-12-05T10:00", "end": "2026-12-05T16:00", "color": "#b45309", "url": "/events/winter-fair" } ]
Some notes on this setup:
- The inline
style="height: 420px"is deliberate. With an inline height, month view stays fixed and shows "+N more" on busy days. Without one, it grows to fit every event, which can push a sidebar far down the page. Only an inline style counts. A height from your stylesheet or a utility class is treated as no height. - Extra fields like
urlare kept and passed back inonEventClick, so the widget can link to each event's page. descriptionbecomes the tooltip when someone hovers over an event.- When the feed changes (after a CMS publish, say), call
widget.refresh()to clear the cache and fetch again.
For more on filtering and loading strategies, see JavaScript event calendar: load, display and filter events.
A drop-in embed snippet for many pages
When the same widget appears on many pages or sites, configure it with HTML instead of copying JavaScript around. The loader below finds every [data-calendar-widget] element. It adds the library's CSS and JS once, then creates one calendar per element from its data-* attributes. dataset maps data-feed to dataset.feed and data-days-forward to dataset.daysForward.
// calendar-widget.js (function () { const CSS_URL = 'https://unpkg.com/simple-calendar-js/dist/simple-calendar-js.min.css'; const JS_URL = 'https://unpkg.com/simple-calendar-js/dist/simple-calendar-js.min.js'; function ensureAssets() { if (!document.querySelector('link[data-scjs]')) { const link = document.createElement('link'); link.rel = 'stylesheet'; link.href = CSS_URL; link.dataset.scjs = ''; document.head.appendChild(link); } if (window.SimpleCalendarJs) return Promise.resolve(); return new Promise((resolve, reject) => { const script = document.createElement('script'); script.src = JS_URL; script.onload = resolve; script.onerror = reject; document.head.appendChild(script); }); } function mount(el) { const { feed, view = 'list', locale = 'default', height = '420', daysForward = '30' } = el.dataset; el.style.height = height + 'px'; // set inline, so month view stays fixed-height if (window.matchMedia('(prefers-color-scheme: dark)').matches) el.classList.add('uc-dark'); return new SimpleCalendarJs(el, { defaultView: view, enabledViews: ['list', 'month'], listDaysForward: Number(daysForward), locale, showYearPicker: false, fetchEvents: async (start, end) => { const res = await fetch(feed); const events = await res.json(); return events .map((e) => ({ ...e, start: new Date(e.start), end: new Date(e.end) })) .filter((e) => e.end >= start && e.start <= end); }, onEventClick: (event) => { if (event.url) window.location.href = event.url; } }); } ensureAssets().then(() => { document.querySelectorAll('[data-calendar-widget]').forEach(mount); }); })();
Each page then needs only this:
<div data-calendar-widget data-feed="/events.json" data-view="list" data-locale="fr-FR" data-days-forward="45"></div> <script src="/js/calendar-widget.js" defer></script>
This works well when you embed in a CMS, which is often the only practical option. The walkthrough on adding a calendar to WordPress without a plugin uses the same pattern. One caveat: if the feed is on a different domain than the page, that server has to send CORS headers for fetch to succeed.
An inline date picker widget
For a booking or enquiry form, switch the mode and write the selection into a form field:
<form> <div id="date-widget" style="height: 340px; max-width: 320px"></div> <input type="hidden" name="date" id="date-field"> <button type="submit">Request this date</button> </form> <script> const picker = new SimpleCalendarJs('#date-widget', { mode: 'date-picker', weekStartsOn: 1, showViewSwitcher: false, onDateSelect: (date) => { const pad = (n) => String(n).padStart(2, '0'); document.getElementById('date-field').value = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`; } }); </script>
Use mode: 'range-picker' with onRangeSelect(start, end) for check-in/check-out style selection, and clearSelection() to reset when the form resets. If the widget only ever picks dates and you never show events, flatpickr or Vanilla Calendar Pro are equally good choices, and both are MIT-licensed.
On licensing: SimpleCalendarJS is free for personal, educational and open source projects. A client website, a SaaS or any other commercial project needs a license per project; see pricing. You can try configurations in the sandbox before deciding.
Need a calendar in your app?
SimpleCalendarJS: ~14 KB gzipped, zero dependencies, works in any framework. Free for personal use.
Making the Widget Fit the Host Page
Widgets live inside someone else's CSS, and most widget bugs come from that.
Scope your overrides
Set theme variables on .uc-calendar under a wrapper ID (as above with #events-widget .uc-calendar), not globally. Then two widgets on the same page can look different, and your overrides don't leak into the host page. The full list of variables and a dark-mode walkthrough are in customising calendar themes.
Watch for aggressive host styles
Themes that set button { width: 100% } or table td { padding: 20px } globally will break any widget, hand-rolled or library. Check the widget on the actual theme, and if the host's CSS wins, increase your selector's specificity under the wrapper. When you need complete isolation, for example a widget you distribute to third-party sites, an iframe pointing to a page you host gives you hard CSS boundaries, at the cost of fixed sizing.
Dark mode is opt-in
SimpleCalendarJS switches to dark when you add uc-dark to the container or a parent. It doesn't follow the operating system on its own. The embed loader above checks prefers-color-scheme once at mount. If the host site has its own dark-mode toggle, toggle uc-dark along with it.
Size for the container, not the viewport
Use max-width on the wrapper and let the calendar fill it. In very narrow spaces, prefer list view and weekdayFormat: 'narrow' (single-letter weekdays). A seven-column month grid at 250 px wide is legible, but event titles in it aren't.
Choosing the Right Calendar Widget
Ask what the widget has to do:
- Show a public Google Calendar with no custom styling, and you have 500 px or more to spare. Use Google's iframe embed. It's the least work.
- Show the current month and highlight a few dates. Write the ~60-line vanilla widget above. No dependency, full control.
- Let users pick a date or range inside a form. flatpickr with
inline: trueor Vanilla Calendar Pro (both MIT), or SimpleCalendarJS's picker modes if you also show events elsewhere on the site. - Show events with times, titles, colors and tooltips. Use an event calendar component. SimpleCalendarJS covers list, month, week and day in ~14 KB gzipped. For a broader comparison, see the best JavaScript calendar libraries compared by bundle size.
- Show resource timelines or recurring-rule-heavy schedules. That isn't a widget anymore. Look at a full scheduler that supports resource views and RRULE natively.
Sources & Further Reading
- Share your calendar with others (embed a calendar) — Google Calendar Help
- Options — flatpickr
- flatpickr releases — GitHub
- flatpickr latest package metadata — npm registry
- vanilla-calendar-pro — GitHub
- vanilla-calendar-pro latest package metadata — npm registry
- Intl.DateTimeFormat — MDN Web Docs
- HTMLElement: dataset property — MDN Web Docs
- SimpleCalendarJS documentation
Image Credits
- Cover: Modern workspace with laptop and 2025 calendar — Pexels
Image free to use under the Pexels License.
Frequently Asked Questions
Is there a free JavaScript calendar widget?
Yes. flatpickr and Vanilla Calendar Pro are both MIT-licensed date pickers that can render inline. The hand-rolled widget in this post costs nothing either. SimpleCalendarJS is free for personal, educational and open source projects. Commercial use, including client websites, needs a paid license.
Can I add a JavaScript calendar widget to WordPress, Webflow or Squarespace?
Usually, yes. Paste a container div plus the script and CSS tags into a custom HTML or embed block. Some editors strip script tags or require a paid plan for custom code. In that case, add the script to the site-wide footer injection and leave only the div in the page.
Does a calendar widget need a backend?
No. A widget can read a static JSON file hosted next to the page, a public API, or a feed your CMS generates. It only needs a server endpoint if visitors change data, for example by booking a slot or adding an event.
How do I start a calendar widget's week on Monday?
In a hand-rolled grid, shift the first-day offset with (firstDay.getDay() - weekStartsOn + 7) % 7, where 1 means Monday. In SimpleCalendarJS, pass weekStartsOn: 1. flatpickr does this through its locale settings.
How do I make a calendar widget responsive?
Give the widget a percentage or max-width instead of a fixed pixel width, and let the grid columns share the width evenly (table-layout: fixed, or a seven-column CSS grid). In narrow sidebars, use narrow weekday labels and a list view, which reads better than a cramped month grid.
Can a calendar widget show events from Google Calendar?
Yes. Load the events from the Google Calendar API (or from a public calendar's feed through your server), convert them to your widget's event format, and render them. You keep full control of styling, which the official Google iframe embed doesn't give you.
Add a calendar to your app today
Free for personal projects. $49/year or $199 lifetime per commercial project.



