How to Add a Calendar to an Astro Site (Zero-Framework Overhead)

You chose Astro because it ships zero JavaScript by default. Your pages are fast, your Lighthouse scores are green, and your content renders at the edge in milliseconds. Then you need to add a calendar — and suddenly you're importing React, configuring hydration directives, and watching your bundle balloon past 100 KB for a single interactive component. There's a better path.

The Astro calendar problem

Astro's architecture is built on islands — isolated interactive components floating in a sea of static HTML. Everything is server-rendered by default. JavaScript only ships to the browser for components you explicitly mark with a client:* directive. This is what makes Astro sites so fast: a typical content page ships 0 KB of client-side JavaScript.

The problem starts when you search for "Astro calendar." Most results point to React-based libraries — FullCalendar, react-big-calendar, Syncfusion — that require a React island. A React island doesn't just ship the calendar code. It ships the React runtime itself: ~40 KB gzipped of framework JavaScript before a single calendar event renders.

Astro's official documentation on framework components makes this clear: every framework component needs a client:* directive to become interactive, and each directive comes with trade-offs. client:load hydrates immediately but risks hydration mismatches. client:only avoids mismatches but skips server rendering entirely — your calendar is invisible until JavaScript loads.

For a framework built on shipping less JavaScript, pulling in an entire UI runtime for one component is a steep price.

What each approach actually costs

Here's what it takes to get a working interactive calendar in Astro with each major library:

The "Requires Framework Runtime" column is the key. React-based calendars don't just add calendar code — they add the entire React reconciler, virtual DOM, and event system. In a regular React app that cost is shared across every component. In Astro, your calendar island might be the only reason React exists on the page, making that ~40 KB pure overhead.

Option 1: The React island path

If you follow the most common advice online, you'll create a React component and wrap it in a client:only island:

// src/components/BigCalendar.jsx
import { Calendar, dayjsLocalizer } from 'react-big-calendar';
import dayjs from 'dayjs';
import 'react-big-calendar/lib/css/react-big-calendar.css';

const localizer = dayjsLocalizer(dayjs);

export default function BigCalendar({ events }) {
  return (
    <div style={{ height: 600 }}>
      <Calendar
        localizer={localizer}
        events={events}
        startAccessor="start"
        endAccessor="end"
      />
    </div>
  );
}

---
// src/pages/calendar.astro
import BigCalendar from '../components/BigCalendar.jsx';
---

<main>
  <h1>Team Calendar</h1>
  <BigCalendar client:only="react" events={[]} />
</main>

This works, but the trade-offs are significant:

• ~95–100 KB gzipped ships to the browser (React runtime + calendar + localizer)
• client:only means no server-rendered HTML for the calendar — users see nothing until JS loads
• You need @astrojs/react installed and configured in astro.config.mjs
• You can't pass functions as props across the island boundary (Astro cannot serialize functions from server to client)
• Event data must be serialized — no passing complex objects or callbacks from the .astro page

You've effectively turned Astro's biggest advantage — zero client JS — into a liability for that section of the page.

Option 2: The vanilla JS path (recommended)

Astro has first-class support for vanilla JavaScript through standard <script> tags. Scripts in .astro components are automatically bundled as ES modules, processed by Vite, and injected into the page. No client:* directive required — they just run on the client.

Here's how to add a calendar to an Astro site using SimpleCalendarJS — ~14 KB gzipped, zero dependencies, no framework runtime:

npm install simple-calendar-js

---
// src/pages/calendar.astro
import Layout from '../layouts/Layout.astro';
---

<Layout title="Team Calendar">
  <main>
    <h1>Team Calendar</h1>
    <div id="calendar"></div>
  </main>
</Layout>

<script>
  import SimpleCalendarJs from 'simple-calendar-js';
  import 'simple-calendar-js/dist/simple-calendar-js.min.css';

  const container = document.getElementById('calendar');

  const calendar = new SimpleCalendarJs(container, {
    defaultView: 'month',
    locale: 'en-US',
    enabledViews: ['month', 'week', 'day'],

    fetchEvents: async (start, end) => {
      const res = await fetch(
        `/api/events?from=${start.toISOString()}&to=${end.toISOString()}`
      );
      return res.json();
    },

    onEventClick: (event) => {
      console.log('Event clicked:', event);
    },

    onSlotClick: (date) => {
      console.log('Slot clicked:', date);
    },
  });
</script>

That's the entire implementation. No React. No @astrojs/react. No client:only. No hydration directive. Astro bundles the <script> as an ES module, and the calendar initialises when the page loads. The rest of your page — the layout, the <h1>, the navigation — remains static HTML with zero JavaScript.

What this gives you

• Month, week, and day views with a built-in navigation toolbar
• Async event fetching — fetchEvents fires with the visible date range on every navigation, so you only load what's on screen
• Click handlers — onEventClick for existing events, onSlotClick for empty time slots
• 34+ locales built in — pass locale: 'pt-BR' or locale: 'ja-JP' and the calendar renders in that language
• ~14 KB total JavaScript added to the page — down from ~95–100 KB with a React island

Making it a reusable Astro component

If you need the calendar on multiple pages, extract it into a reusable .astro component:

---
// src/components/Calendar.astro
const { locale = 'en-US', apiEndpoint = '/api/events' } = Astro.props;
---

<div
  id="calendar"
  data-locale={locale}
  data-api={apiEndpoint}
></div>

<script>
  import SimpleCalendarJs from 'simple-calendar-js';
  import 'simple-calendar-js/dist/simple-calendar-js.min.css';

  const container = document.getElementById('calendar');
  const locale = container.dataset.locale;
  const apiEndpoint = container.dataset.api;

  const calendar = new SimpleCalendarJs(container, {
    defaultView: 'month',
    locale,
    enabledViews: ['month', 'week', 'day'],

    fetchEvents: async (start, end) => {
      const res = await fetch(
        `${apiEndpoint}?from=${start.toISOString()}&to=${end.toISOString()}`
      );
      return res.json();
    },

    onEventClick: (event) => {
      console.log('Event clicked:', event);
    },
  });
</script>

---
// src/pages/calendar.astro
import Layout from '../layouts/Layout.astro';
import Calendar from '../components/Calendar.astro';
---

<Layout title="Team Calendar">
  <main>
    <h1>Team Calendar</h1>
    <Calendar locale="en-US" apiEndpoint="/api/events" />
  </main>
</Layout>

Notice the pattern: server-side props (locale, apiEndpoint) are passed to the client via data-* attributes on the container element. This is Astro's recommended approach for sending data from the server to client-side scripts — no serialization issues, no framework boundary limitations.

Theming with CSS custom properties

SimpleCalendarJS uses CSS custom properties, which work identically whether you're using Astro's scoped styles, Tailwind, or global CSS:

.uc-calendar {
  --cal-primary: #7c3aed;
  --cal-primary-dark: #6d28d9;
  --cal-today-bg: #f5f3ff;
  --cal-font-size: 14px;
}

For dark mode with Astro's built-in class-based toggling:

.dark .uc-calendar {
  --cal-bg: #0f172a;
  --cal-text: #e2e8f0;
  --cal-border: #1e293b;
  --cal-today-bg: #1e1b4b;
}

Four variables and your calendar matches your design system. No eventPropGetter callbacks, no deeply nested selector overrides, no !important flags.

Bundle impact: preserving Astro's zero-JS advantage

Astro's core promise is performance. A typical Astro content site ships 0 KB of client-side JavaScript. The moment you add an interactive component, that number goes up — the question is by how much.

With SimpleCalendarJS, your Astro site goes from 0 KB to 14 KB — a full interactive event calendar for less JavaScript than most hero image lazy-loaders. With a React island calendar, you're shipping 6–7x more JavaScript, and the calendar section isn't even server-rendered.

When to use a React island for your calendar

There are valid reasons to bring React into an Astro project for a calendar:

• Existing React codebase: If your Astro site wraps a React app or shares components with a React project, using the same calendar keeps the API consistent
• Drag-and-drop rescheduling: react-big-calendar has mature drag-and-drop support for moving and resizing events directly on the grid
• Shared island state: If your calendar needs to share reactive state with other React components on the same page (e.g. a sidebar filter updating the calendar), a React island keeps that state management simple
• Agenda/list view: react-big-calendar includes a built-in agenda view for displaying events in a scrollable list

For the majority of Astro sites — blogs, marketing pages, documentation, dashboards — that need to display events and let users navigate between views, a vanilla JS calendar keeps your bundle lean and your architecture simple.

Summary

• Astro ships 0 KB of JavaScript by default — adding a React-based calendar breaks that promise with ~80–100 KB of framework runtime plus calendar code
• React islands in Astro require client:only, which skips server rendering and shows nothing until JavaScript loads — the opposite of Astro's content-first philosophy
• Vanilla JS calendars work natively in Astro through standard <script> tags — no client:* directive, no framework adapter, no hydration workarounds
• SimpleCalendarJS adds a full event calendar (month, week, day views, async fetching, click handlers, 34+ locales) in ~14 KB gzipped — preserving most of Astro's zero-JS advantage
• Use data-* attributes to pass server-side props to your calendar's <script> tag, following Astro's recommended pattern for server-to-client data transfer

---

Sources & Further Reading

Research & References

• Astro Client-Side Scripts Documentation — astro.build
• Astro Framework Components (client directives) — astro.build
• Astro Islands Architecture — astro.build
• Astro's Client Directives: When and Where to Use Each — DEV Community
• Building a Calendar Interface in Astro — myles.garden
• Refactor a React Astro Island to Vanilla JS — egghead.io
• Vanilla Astro, No Framework Needed — Telerik
• React Hydration Error in Astro — withastro/astro #7709
• Astro Calendar with FullCalendar + Tailwind — GitHub
• Optimizing React Component Libraries for AstroJS — laur.design

Image Credits

• Cover: Workplace with Modern Laptop with Program Code on Screen — Pexels

All images free to use under the Pexels License.