Calendar

The Calendar component provides a rich date selection interface supporting single dates, multiple dates, or date ranges. It includes month navigation, customizable date constraints, and various display options.

Features

• Selection modes: single date, multiple dates, or date range
• Month navigation with previous/next buttons
• Optional year selector dropdown
• Min/max date constraints
• Custom disabled dates (array or function)
• Week numbers display
• Fixed weeks option for consistent height
• Multi-month display
• Customizable first day of week
• Outside days visibility control
• Initial focus support for accessibility

Usage

import { Calendar } from '@loke/design-system/calendar';

export default function Example() {
  const [date, setDate] = useState<Date | undefined>(new Date());

  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
    />
  );
}

Tips:

• Use mode="single" for selecting a single date.
• Use mode="range" for date range selection (e.g., booking dates).
• Set minDate and maxDate to constrain selectable dates.
• Enable showWeekNumber for calendars that need week-based navigation.

Props

Examples

Single date selection

const [date, setDate] = useState<Date | undefined>(new Date());

<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
/>

Multiple date selection

const [dates, setDates] = useState<Date[]>([]);

<Calendar
  mode="multiple"
  selected={dates}
  onSelect={setDates}
/>

Date range selection

const [range, setRange] = useState<DateRange | undefined>();

<Calendar
  mode="range"
  selected={range}
  onSelect={setRange}
  numberOfMonths={2}
/>

Disabled dates

// Disable weekends
<Calendar
  mode="single"
  disabled={(date) => date.getDay() === 0 || date.getDay() === 6}
/>

// Or disable specific dates
<Calendar
  mode="single"
  disabled={[new Date(2024, 0, 1), new Date(2024, 11, 25)]}
/>

Min and max dates

<Calendar
  mode="single"
  minDate={new Date()}
  maxDate={new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)}
/>

Multiple months

<Calendar
  mode="range"
  numberOfMonths={2}
/>

Week numbers

<Calendar
  mode="single"
  showWeekNumber
/>

Year selector

<Calendar
  mode="single"
  captionProps={{ showYearSelector: true }}
/>

Accessibility

• Calendar uses semantic table markup for screen reader compatibility.
• Keyboard navigation with arrow keys moves between days.
• Days are focusable with proper tabIndex management.
• Selected state is conveyed via aria-selected attributes.
• Disabled days are marked with disabled attribute.
• Use initialFocus to ensure keyboard users land on a meaningful date when the calendar opens.

Best practices

• Set appropriate minDate/maxDate constraints to prevent invalid selections.
• Use mode="range" with numberOfMonths={2} for better date range UX.
• Enable showWeekNumber for business applications that reference week numbers.
• Consider fixedWeeks to prevent layout shifts when navigating months.
• Use captionProps.showYearSelector when users need to navigate to distant dates.
• Pair with Label component for form accessibility.