How I Created Vanilla Calendar Pro — A Lightweight and Flexible JavaScript Calendar with TypeScript

Hello, Dev Community!

Honestly, I hesitated for a long time before writing this article. I understand that there might be comments saying, "Just another unnecessary datepicker." But today, with Vanilla Calendar Pro earning over 480 stars on GitHub and receiving 17,000 downloads per month, I decided to share my story.

Let me clarify upfront: I'm not claiming to be the best calendar or datepicker developer. This article is about my first experience with open source, how I created a project from scratch, and how it became useful to other developers.

How It All Started

In the summer of 2022, I needed to implement an event calendar for a project. The requirements were simple:

• It had to work seamlessly in a modal window.
• It needed to support custom styling to match the design.
• Clicking a date would redirect the user to an event page.

At first glance, it seemed like a straightforward task. But I couldn’t find a suitable solution. Most existing calendars either lacked the necessary features or were too bulky, with styles that were difficult to adapt to the project’s design.

Sure, I could have asked the designer to simplify the layout or just accepted a minor formatting issue. But honestly, I was intrigued: What if I built my own calendar?

That’s how the first version of Vanilla Calendar Pro was born. The term "Vanilla" refers to native JavaScript, free of external dependencies. To make it easier to integrate into other projects, I wrote a README with API documentation and examples and published it on NPM.

The First User — And the First Star

Not long after, I received a notification about the first issue in the repository. It came from a developer in Norway, who asked an unexpected question:

"Do you have any plans to add week numbers to the calendar? Here in Norway, using week numbers is very common, and it would be a helpful feature."

This moment made me realize that the calendar could be useful not just for me, but for others as well. But then I asked myself: What do I gain from all this effort? Why should I spend my free time so some guy in Norway can use my calendar? The answer was: Nothing tangible!

However, the thought that I had created something genuinely helpful—that someone could download my calendar, save time on development, and focus on more important tasks—was incredibly inspiring. Even if it didn’t bring me any material rewards, I felt a deep sense of satisfaction knowing that my project was helping others.

So, I began actively improving the calendar, transforming it into a more universal and flexible solution. I also designed the interface myself, aiming to make it not only functional but also user-friendly.

What Sets Vanilla Calendar Pro Apart?

• Flexible layouts: Customize the HTML structure of the calendar completely, adding custom buttons or elements as needed.
• Full style control: Easily override any CSS classes, enabling seamless integration with frameworks like Tailwind CSS.
• Accessibility (a11y): All elements are equipped with aria-labels and support keyboard navigation.
• Interactive popups: Highlight specific days and display additional information directly in the calendar.
• Week numbers: Supports week-based date formats, popular in many countries.
• Time selection: Offers both 12-hour and 24-hour formats, with sliders or manual input.
• Themes: Automatically switches between light and dark themes and supports custom themes.
• Localization and internationalization: Easily adjust the first day of the week, weekends, and holidays for any locale.
• Framework compatibility: Works with React, Vue, Angular, and any other frameworks thanks to its native JavaScript foundation.

And that’s not all! I didn’t even mention the utilities, methods, actions, and extensive configuration options that allow you to customize the calendar to fit virtually any requirements.

Numbers and Documentation

Vanilla Calendar Pro is entirely written in TypeScript, with no external dependencies. The minified file is only ~49.33 KB (or 13.52 KB gzip).

I’ve also prepared detailed documentation, which includes:

• An API reference.
• An Learn page with interactive sandboxes.

📘 Project Website

🔗 GitHub Repository

Conclusion

No, this is not a revolutionary product. It’s just another calendar/datepicker. But for me, it became a significant milestone in my journey with open source. I’m glad I created something useful that could help other developers.

I hope Vanilla Calendar Pro proves helpful to you as well. Thank you for reading!