Cally

Small, feature-rich calendar components

 
<div class="card">
  <calendar-range months="2">
    <svg
      aria-label="Previous"
      slot="previous"
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 24 24"
    >
      <path d="M15.75 19.5 8.25 12l7.5-7.5"></path>
    </svg>
    <svg
      aria-label="Next"
      slot="next"
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 24 24"
    >
      <path d="m8.25 4.5 7.5 7.5-7.5 7.5"></path>
    </svg>
    <div class="grid">
      <calendar-month></calendar-month>
      <calendar-month offset="1"></calendar-month>
    </div>
  </calendar-range>
</div>

Goals

The aim is not to give you a full date picker, instead only the lower-level building blocks that allow you to build your own. You likely already have your own inputs, buttons, popover etc components. So why not use them?

By making minimal assumptions about how the components will look and function, we can keep the bundle size small without compromising on functionality or ability to customize.

Installation

In the simplest scenario, include a script tag in your HTML page. The components are then immediately available for use. For example, using unpkg: 

<script type="module" src="https://unpkg.com/cally"></script>

Alternatively, you can install the package via npm or your preferred package manager: 

npm install cally

Then import the components into your JavaScript or TypeScript file. For example, using ES modules: 

import "cally";

Quick start

Assuming you have followed the installation instructions, the next step is to put the components to use.

Single date

For a single date, use the <calendar-date> component, and place inside it a <calendar-month> component. 

<calendar-date>
  <calendar-month></calendar-month>
</calendar-date>

Date range

For a date range, use the <calendar-range> component, and place inside it a <calendar-month> component. 
<calendar-range>
  <calendar-month></calendar-month>
</calendar-range>

Multiple months

To display multiple months, add more <calendar-month> components inside <calendar-range> or <calendar-date> components. You must set the months attribute of the range and date calendars to the number of months you will display. Then configure the offset attribute of each <calendar-month> to specify the month it represents relative to the first visible month.

By default, the <calendar-month> components will stack vertically. You will likely want to use flexbox or css grid to improve the layout as seen below. 

<style>
  .grid {
    display: flex;
    gap: 1em;
    justify-content: center;
    flex-wrap: wrap;
  }
</style>
<calendar-range months="2">
  <div class="grid">
    <calendar-month></calendar-month>
    <calendar-month offset="1"></calendar-month>
  </div>
</calendar-range>

Next steps

For a detailed look at each component, check out the respective component API docs. The guides section offers walkthroughs on theming, framework integration, and usage with existing components.

If you are evaluating accessibility, please read the accessibility statement to understand how these components work, how they have been tested, and any known issues.

If you have an issue or feature request, please open an issue in the repository.

Acknowledgments

Cally is a spiritual successor to my earlier work on Duet date picker. Shout out to everyone that made it possible to open source that. The component APIs are partially inspired by the Date and Time components from React ARIA Components, though there is some amount of convergent evolution. Much appreciation to Nikos Gereoudakis for transferring ownership of the cally package on npm. And finally, thanks to @Uppercod for his work on Atomico.