Calendar Component

The Calendar component provides an intuitive interface for date selection. It features smooth animations, internationalization, keyboard navigation, and comprehensive accessibility support.

Key Features

• Interactive Calendar: Visual date selection with month/year navigation

• Smart Date Management: Handles date constraints and validations

• Keyboard Navigation: Full keyboard support for date selection

• Localization: Adapts to user’s locale settings

• Accessibility: Built with ARIA support and screen reader compatibility

Keyboard Support

• Arrow Keys: Navigate between days
• PageUp/PageDown: Previous/Next month
• Enter/Space: Select focused date
• Tab: Navigate focusable elements
• Escape: Close month picker

Date Picker

The Date Picker is a combination of a calendar component and a popover component. Creating an easy to use form element for date selection.

1
<DatePicker />

Basic Usage

Create a simple calendar with default settings:

1
<Calendar class="w-min" />

With Initial Value

Specify an initial selected date as a Date object:

1
<Calendar value={new Date(2024, 0, 24)} />

Multiple Date Selection

The Calendar component also supports multiple date selection. To enable this feature, set the mode prop to multiple. Click one date to select it and click another date to select it.

1
<Calendar mode="multiple" value={[new Date(2024, 0, 24), new Date(2024, 0, 25)]}/>

Multiple Selection Constraints

You can set the maxSelectable prop to limit the number of dates that can be selected in multiple mode. Selecting more than the maximum will deselect in the order that the dates were selected.

1
<Calendar mode="multiple" maxSelectable={3} />

Date Range Selection

The Calendar component also supports date range selection. To enable this feature, set the mode prop to range. Click one date to select the start date and click another date to select the end date.

1
<Calendar mode="range" />

With Initial Value

Specify an initial selected date range as a Date object:

1
<Calendar value={{ start: new Date(2025, 2, 24), end: new Date(2025, 2, 28) }} mode="range" />

Range Selection Constraints

You can set the minRange and maxRange props to limit the range of dates that can be selected. The hover higlighting will only be applied to dates within the range. Clicking a date outside of the range will start a new range selection.

1
<Calendar mode="range" minRange={3} maxRange={5} />

More Date Selection Constraints

Disable Dates Outside of a Range

Limit selectable dates with availableDateRange prop. If the todays date is outside of the range, the calendar will automatically adjust to the nearest enabled date:

1
<Calendar
2
    availableDateRange={{ start: new Date(2024, 2, 1), end: new Date(2024, 7, 21) }}
3
/>

Available Days of Week

You can set the availableDaysOfWeek prop to limit the days of the week that can be selected. Start counting from 0 for Sunday and 6 for Saturday.

1
<Calendar availableDaysOfWeek={[0, 1, 3, 4]} />

Custom Event Listeners

You can listen to the selected custom event emitted by the calendar component, returns the selected date(s) in ISO string format. Read Component Architecture for more information on how to use custom events.

Waiting for events to be emitted… (Click on the calendar to see the events)

1
CustomEvent<{
2
  id?: string;
3
  name?: string;
4
  mode?: 'single' | 'multiple' | 'range';
5
  selectedDates?: //selected dates as ISO strings
6
  | string //single mode
7
    | string[] //multiple mode
8
    | { start: string; end: string }; //range mode
9
}>;

Calendar Component Props API

Calendar Functions API

The calendar component provides a set of functions to interact with the calendar:

1
export type CalendarDate = Date | Date[] | { start: Date | undefined; end: Date | undefined };

Function Examples

The Calendar component exposes several methods for programmatic control. Below are interactive examples of how to use each method.

1
import type { CalendarElement } from '@/components/NST-components/UI/calendar/data';
2
import { ready } from '@/components/NST-components/base';
3

4
ready(
5
  document.querySelector<CalendarElement>('#set-date-calendar')
6
).then((calendar) => {
7
  if (!calendar) return;
8
  document
9
    .querySelector<HTMLButtonElement>('#set-date-button')
10
    ?.addEventListener('click', () => {
11
      calendar.dates = new Date();
12
    });
13
});

1
import type { CalendarElement } from '@/components/NST-components/UI/calendar/data';
2
import { ready } from '@/components/NST-components/base';
3

4
ready(
5
  document.querySelector<CalendarElement>('#reset-date-calendar')
6
).then((calendar) => {
7
  document
8
    .querySelector<HTMLButtonElement>('#reset-date-button')
9
    ?.addEventListener('click', () => {
10
      calendar?.resetDate();
11
    });
12
});

1
import type { CalendarElement } from '@/components/NST-components/UI/calendar/data';
2
import { ready } from '@/components/NST-components/base';
3

4
ready(
5
  document.querySelector<CalendarElement>('#set-available-range-calendar')
6
).then((calendar) => {
7
  if (!calendar) return;
8
  document
9
    .querySelector<HTMLButtonElement>('#set-available-range-button')
10
    ?.addEventListener('click', () => {
11
      const today = new Date();
12
      const endDate = new Date(today);
13
      endDate.setDate(endDate.getDate() + 7);
14
      calendar.availableDateRange = {
15
        start: today,
16
        end: endDate,
17
      };
18
    });
19
});

1
import type { CalendarElement } from '@/components/NST-components/UI/calendar/data';
2
import { ready } from '@/components/NST-components/base';
3

4
ready(
5
  document.querySelector<CalendarElement>('#set-available-dates-calendar')
6
).then((calendar) => {
7
  if (!calendar) return;
8
  document
9
    .querySelector<HTMLButtonElement>('#set-available-dates-button')
10
    ?.addEventListener('click', () => {
11
      const dates = [];
12
      const today = new Date();
13
      // Get all weekends in the current month
14
      const currentMonth = today.getMonth();
15
      const date = new Date(today.getFullYear(), currentMonth, 1);
16

17
      while (date.getMonth() === currentMonth) {
18
        if (date.getDay() === 0 || date.getDay() === 6) {
19
          dates.push(new Date(date));
20
        }
21
        date.setDate(date.getDate() + 1);
22
      }
23
      calendar.availableDates = dates;
24
    });
25
});

1
import type { CalendarElement } from '@/components/NST-components/UI/calendar/data';
2
import { ready } from '@/components/NST-components/base';
3

4
ready(
5
  document.querySelector<CalendarElement>(
6
    '#unavailable-dates-this-month-calendar'
7
  )
8
).then((calendar) => {
9
  if (!calendar) return;
10
  document
11
    .querySelector<HTMLButtonElement>(
12
      '#set-unavailable-dates-this-month-button'
13
    )
14
    ?.addEventListener('click', () => {
15
      const dates = [];
16
      const today = new Date();
17
      const currentMonth = today.getMonth();
18
      const date = new Date(today.getFullYear(), currentMonth, 1);
19

20
      while (date.getMonth() === currentMonth) {
21
        dates.push(new Date(date));
22
        date.setDate(date.getDate() + 1);
23
      }
24

25
      calendar.unavailableDates = dates;
26
    });
27
});

1
import type { CalendarElement } from '@/components/NST-components/UI/calendar/data';
2
import { ready } from '@/components/NST-components/base';
3

4
ready(
5
  document.querySelector<CalendarElement>('#available-days-of-week-calendar')
6
).then((calendar) => {
7
  if (!calendar) return;
8
  document
9
    .querySelector<HTMLButtonElement>('#set-available-days-of-week-button')
10
    ?.addEventListener('click', () => {
11
      const days = [1, 3, 5];
12
      calendar.availableDaysOfWeek = days;
13
    });
14
});

Error State

The calendar component also supports an error state when the state dataset property is set to error. The only time that the error state will be set by the component automatically is if available/unavailable dates are modified and a selected date is no longer available.

1
<Calendar data-state="error" />