cally

If you have installed Cally via npm, import it in your JavaScript entry point to register the custom elements.

import "cally";

Install the cally package using npm to use the calendar components in your project.

npm install cally

You can use Cally directly in an HTML file without a build step by importing the module from a CDN.

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

Cally components are web components that you can use directly in your HTML. For example, to create a range selector that displays two months, use the <calendar-range> component with the months attribute and include multiple <calendar-month> elements. You can use the offset attribute on <calendar-month> to control which month is displayed relative to the range.

<calendar-range months="2">
  <calendar-month></calendar-month>
  <calendar-month offset="1"></calendar-month>
</calendar-range>

The CalendarBase component provides event listeners to react to user interactions with specific dates. These events are dispatched as CustomEvent objects containing a PlainDate object.

• onselectday: Triggered when a user selects a date. Expects a callback with signature (e: CustomEvent<PlainDate>) => void.
• onfocusday: Triggered when a date gains focus. Expects a callback with signature (e: CustomEvent<PlainDate>) => void.
• onhoverday: Triggered when a user hovers over a date. Expects a callback with signature (e: CustomEvent<PlainDate>) => void.

Cally provides a set of web components for calendar functionality. You can import the following components from the main entry point:

• CalendarMonth: Represents a single month view.
• CalendarDate: Represents a single date selection.
• CalendarRange: Represents a range of dates.
• CalendarMulti: Represents multiple discrete date selections.
• CalendarSelectYear: A component for selecting a year.
• CalendarSelectMonth: A component for selecting a month.
• CalendarHeading: A component for displaying calendar headings.

import {
  CalendarMonth,
  CalendarDate,
  CalendarRange,
  CalendarMulti,
  CalendarSelectYear,
  CalendarSelectMonth,
  CalendarHeading,
} from "cally";

The PlainYearMonth class represents a specific month in a specific year. It is useful for calendar logic that does not require a specific day.

Key features:

• Creation: Instantiate via new PlainYearMonth(year, month) or convert from a PlainDate using .toPlainYearMonth().
• Arithmetic: Use .add(duration) where duration can include months or years.
• Comparison: Use .equals(dateOrYearMonth) to compare against a PlainDate or another PlainYearMonth, or use the static PlainYearMonth.compare(a, b) method.
• Conversion: Use .toPlainDate() to get a PlainDate representing the 1st day of that month.

The PlainDate class provides a lightweight way to handle calendar dates (year, month, day) with arithmetic and comparison capabilities. It is designed to be a drop-in replacement for the upcoming Temporal API.

Key features:

• Creation: Instantiate via new PlainDate(year, month, day) or use PlainDate.from(value) where value is an ISO date string (YYYY-MM-DD) or a JavaScript Date object.
• Arithmetic: Use .add(duration) to add days, months, or years. Note that arithmetic is constrained to ensure valid dates (e.g., adding 1 month to March 31st results in April 30th).
• Comparison: Use PlainDate.compare(a, b) to get a result of -1, 0, or 1, or use .equals(otherDate) for a boolean check.
• Conversion: Use .toString() for ISO format or .toPlainYearMonth() to convert to a PlainYearMonth instance.

The <calendar-date> component exposes the following interface:

Events

• change: Dispatched when the selected date changes.
• onFocusDay: A CustomEvent<Date> dispatched when a specific day gains focus.
• onPageChange: A CustomEvent<PageChangeDetail> dispatched when the calendar view changes (e.g., navigating to a different month).

Methods

• focus(options?: CalendarFocusOptions): Programmatically sets focus within the calendar. Accepts an optional options object of type CalendarFocusOptions.

The CalendarBase component exposes several CSS Shadow Parts that allow you to customize its internal structure via your own CSS:

• container: The main wrapper for the calendar (a div with role="group").
• header: The top section containing navigation and the heading.
• heading: The slot for the calendar heading.
• months: The slot where the month views are rendered.
• button: The base style for the navigation buttons. Note that buttons can also have specific parts like button previous or button next depending on the implementation, and a button disabled part when the onclick handler is missing.

If you are building wrappers for Cally components in frameworks like React or Vue, you can use the exported Props types to ensure type safety. These types represent the component's properties, excluding standard HTMLElement and AtomicoThis properties.

Available prop types:

• CalendarMonthProps
• CalendarDateProps
• CalendarRangeProps
• CalendarMultiProps
• CalendarSelectYearProps
• CalendarSelectMonthProps
• CalendarHeadingProps