Skip to main content

Calendar

Calendar displays a month grid that lets people choose a date or date range, such as a booking period or a reporting window.

Import

import { Calendar } from '@vortexlabs/vortex';
import type { CalendarProps } from '@vortexlabs/vortex';

Other links

Storybook
M
T
W
T
F
S
S
<Calendar
  previousAriaLabel="Previous"
  nextAriaLabel="Next"
  locale="en-US"
  monthFormat="short"
  firstWeekDay={1}
/>

Features

  • Selects a single date or a date range.
  • Supports controlled values and initial selections.
  • Limits available dates and marks dates with events.
  • Provides month and year views for navigation.
  • Localizes Gregorian labels and supports keyboard navigation.

Single Selection

Set defaultValue to start with a selected date. Use local Date values; JavaScript month indexes start at zero.

M
T
W
T
F
S
S
"use client";

import { Calendar } from "@vortexlabs/vortex";

export const CalendarSingleExample = () => (
  <Calendar
    defaultValue={new Date(2026, 9, 13)}
    previousAriaLabel="Previous"
    nextAriaLabel="Next"
  />
);

Controlled Selection

Set value and update it in onChange to keep the selected date in your application state. Use null for no selection.

M
T
W
T
F
S
S
Choose a date
"use client";

import { Calendar, Stack, Text } from "@vortexlabs/vortex";
import { useState } from "react";

export const CalendarControlledExample = () => {
  const [value, setValue] = useState<Date | null>(null);

  return (
    <Stack gap={4} align="start">
      <Calendar
        value={value}
        onChange={({ value }) => setValue(value)}
        previousAriaLabel="Previous"
        nextAriaLabel="Next"
      />
      <Text attributes={{ "aria-live": "polite" }}>
        {value ? value.toLocaleDateString("en-GB") : "Choose a date"}
      </Text>
    </Stack>
  );
};

Date Ranges

Use selection="range" for a start and end date. The first selection sets start; end stays null until another date is picked.

M
T
W
T
F
S
S
13/10/2026 – 19/10/2026
"use client";

import { Calendar, type CalendarRangeValue, Stack, Text } from "@vortexlabs/vortex";
import { useState } from "react";

export const CalendarRangeExample = () => {
  const [value, setValue] = useState<CalendarRangeValue>({
    start: new Date(2026, 9, 13),
    end: new Date(2026, 9, 19),
  });

  return (
    <Stack gap={4} align="start">
      <Calendar
        selection="range"
        value={value}
        onChange={({ value }) => setValue(value)}
        previousAriaLabel="Previous"
        nextAriaLabel="Next"
      />
      <Text attributes={{ "aria-live": "polite" }}>
        {value.start?.toLocaleDateString("en-GB") ?? "Start date"}
        {" – "}
        {value.end?.toLocaleDateString("en-GB") ?? "Choose an end date"}
      </Text>
    </Stack>
  );
};

Set defaultValue to a { start, end } object for an uncontrolled range. Selecting an earlier date or selecting after a completed range starts a new range.

Available Dates

Set min and max to limit selectable dates. Use isDateDisabled for unavailable dates within those bounds.

M
T
W
T
F
S
S
"use client";

import { Calendar } from "@vortexlabs/vortex";

export const CalendarAvailabilityExample = () => (
  <Calendar
    defaultValue={new Date(2026, 9, 13)}
    min={new Date(2026, 9, 5)}
    max={new Date(2026, 9, 23)}
    isDateDisabled={({ date }) => date.getDay() === 0 || date.getDay() === 6}
    previousAriaLabel="Previous"
    nextAriaLabel="Next"
  />
);

Disabled dates cannot be selected as range endpoints, but a range can span them.

Event Indicators

Use hasDateEvent to mark dates with events. Set eventAriaLabel to describe those events to screen readers.

M
T
W
T
F
S
S
"use client";

import { Calendar } from "@vortexlabs/vortex";

export const CalendarEventsExample = () => (
  <Calendar
    defaultValue={new Date(2026, 9, 13)}
    hasDateEvent={({ date }) => date.getDay() === 2}
    eventAriaLabel="Team meeting"
    previousAriaLabel="Previous"
    nextAriaLabel="Next"
  />
);

Month and Year Navigation

Activate the month or year heading to choose another month or year. Selecting one returns to the date grid without changing the selected date.

Accessibility

Key
Description
TabShiftTab
Move between navigation controls and the calendar grid. Use arrow keys within the grid.
Left arrowRight arrowUp arrowDown arrow
Move between dates, months, or years; horizontal movement follows the reading direction.
HomeEnd
Move to the start or end of the current week or grid row.
Page UpPage Down
Move by a month in the date view or a page in the year view.
ShiftPage UpShiftPage Down
Move by a year in the date view.
EnterSpace
Select the focused date, month, or year, or activate a heading control.
Provide previousAriaLabel and nextAriaLabel, such as ‘Previous’ and ‘Next’, translated for your locale.
Provide eventAriaLabel when using hasDateEvent so screen readers announce marked events.
Disabled dates remain reachable with the arrow keys but cannot be selected.