Introducing ilamy Calendar: A Modern React Calendar Built for Developers

TL;DR: ilamy Calendar is a React-first calendar library that gives you complete control over styling while providing powerful features like drag-and-drop, multiple views, and timezone support out of the box.

Try the live demo → | View docs →

---

Ever tried integrating a calendar into a React app and ended up wrestling with CSS overrides, fighting JavaScript APIs that weren't built for React, or struggling to customize interactions without breaking things? I've been there too many times.

That's why I built ilamy Calendar — a modern, React-first calendar library that actually feels like it belongs in your React codebase.

The Problem with Existing Solutions

• FullCalendar: Powerful but not React-first
• React Big Calendar: Good React integration but limited customization options
• Commercial solutions: Expensive and often overkill for most use cases
• CSS nightmares: Spending more time fighting default styles than building features

I wanted something that was:

• React-first (built for React)
• Fully customizable (without CSS hacks)
• TypeScript native for better DX
• Modern build tools (built with Bun)
• Zero opinions about your design system

---

Features at a Glance

• Drag and Drop Support
• Month / Week / Day / Year views
• Fully customizable via props
• Zero CSS shipped — full design control
• Locale and timezone aware
• Custom event rendering
• Built with Bun from end to end

---

Quick Start

Get up and running in under 2 minutes:

# Using Bun
bun add @ilamy/calendar

# Or npm/pnpm/yarn
npm install @ilamy/calendar
pnpm install @ilamy/calendar
yarn add @ilamy/calendar

Basic Setup

import { IlamyCalendar } from '@ilamy/calendar'

function MyApp() {
  const events = [
    {
      id: '1',
      title: 'Team Meeting',
      start: new Date('2024-01-15T10:00:00'),
      end: new Date('2024-01-15T11:00:00'),
      color: '#3b82f6'
    }
  ]

  return <IlamyCalendar events={events} />
}

Configure Tailwind CSS

One of the bold choices I made: not shipping any CSS. If you’ve ever wrestled with a library’s default styles, you know how frustrating that can be.

Instead, ilamy Calendar gives you clean, unstyled structure which you can style using your own Tailwind config. You need to register the source path in your CSS file to ensure all component styles are included:

/* In your main CSS file (e.g., globals.css) */
@source "../node_modules/@ilamy/calendar/dist";

This tells Tailwind to scan the calendar package for classes and include them in your build. This is especially important since node_modules are typically ignored by Tailwind by default.

Day.js Plugin Configuration

Important: If you're using Day.js in your project (i.e. installed in your package.json dependencies), you'll need to extend it with required plugins:

import dayjs from 'dayjs';
import isSameOrAfter from 'dayjs/plugin/isSameOrAfter.js';
import isSameOrBefore from 'dayjs/plugin/isSameOrBefore.js';
import timezone from 'dayjs/plugin/timezone.js';
import utc from 'dayjs/plugin/utc.js';

dayjs.extend(isSameOrAfter);
dayjs.extend(isSameOrBefore);
dayjs.extend(timezone);
dayjs.extend(utc);

This prevents "isSameOrBefore is not a function" errors when using the calendar.

That's it! You now have a fully functional calendar.

---

Advanced Features & Examples

Custom Event Rendering

Take full control over how events look:

<IlamyCalendar
  events={events}
  renderEvent={(event) => (
    <div className="px-2 py-1 bg-gradient-to-r from-blue-500 to-purple-600 text-white rounded-md shadow-sm">
      <div className="font-semibold">{event.title}</div>
      <div className="text-xs opacity-90">{event.description}</div>
    </div>
  )}
/>

Event Handlers & Interactions

Handle user interactions with ease:

<IlamyCalendar
  events={events}
  onEventClick={(event) => {
    // Open event details modal
    openEventModal(event)
  }}
  onCellClick={(date) => {
    // Create new event
    createEvent(date)
  }}
  onViewChange={(view) => {
    // Track analytics or update URL
    analytics.track('calendar_view_changed', { view })
  }}
/>

Complete API Reference

Here's everything you can customize:

interface CalendarProps {
  // Core functionality
  events?: CalendarEvent[]
  firstDayOfWeek?: 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday'

  // Event handling
  onEventClick?: (event: CalendarEvent) => void
  onCellClick?: (date: Date) => void
  onViewChange?: (view: 'month' | 'week' | 'day' | 'year') => void

  // Customization
  renderEvent?: (event: CalendarEvent) => React.ReactNode
  headerComponent?: React.ReactNode

  // Localization
  locale?: string
  timezone?: string

  // Behavior
  disableCellClick?: boolean
  disableEventClick?: boolean
  disableDragAndDrop?: boolean
  dayMaxEvents?: number

  // Styling
  stickyViewHeader?: boolean
  viewHeaderClassName?: string
}

interface CalendarEvent {
  id: string
  title: string
  start: dayjs.Dayjs | Date | string
  end: dayjs.Dayjs | Date | string
  description?: string
  color?: string
  allDay?: boolean
}

Pro Tips for Better Performance

• Memoize your event renderer:

const renderEvent = useCallback((event: CalendarEvent) => <CustomEventComponent event={event} />, [])

• Use stable event arrays:

const events = useMemo(() => fetchEvents(), [dependency])

---

Built with Modern Tools

Ilamy Calendar leverages the latest tools for the best developer experience:

Tool	Purpose	Why We Chose It
Bun	Package manager, bundler, test runner	Incredibly fast, all-in-one solution
TypeScript	Type safety	Better DX and fewer runtime errors
Tailwind CSS v4	Styling	Utility-first, highly customizable
Day.js	Date manipulation	Lightweight, timezone-aware
Framer Motion	Animations	Smooth, performant animations

---

What's Next

The roadmap is packed with exciting features:

Coming Soon

• Resource Calendar: Visualize events by resources (rooms, people, equipment)

Future Ideas

• Accessibility: ARIA compliance and keyboard navigation
• Performance: Virtual scrolling for large datasets
• Export/Import: iCal, Google Calendar integration

---

Complete Documentation

Interactive Demo

GitHub Repository

---

Join the Community

ilamy Calendar is just getting started, and I'd love your feedback:

• Found a bug? Open an issue
• Have an idea? Start a discussion
• Like the project? Give it a star on GitHub
• Share it! Help other React developers discover Ilamy

---

Thanks for reading, and happy building! 🚀

P.S. If you end up using ilamy Calendar in production, I'd love to hear about it. : )