Date & Calendar Components

Calendar Overview

Calendar components provide an intuitive way for users to select dates. Built following Material Design 3 principles, these components offer flexible display options, internationalization support, and full accessibility features including keyboard navigation and screen reader compatibility. Click the month/year header to quickly jump to any year.

Basic Calendar

With Header

Calendar Variants

Color Variants

Primary (default)

Secondary

Tertiary

With Action Buttons

Disabled State

Inline Calendar Form Field

The inline calendar component is designed for form integration, providing a hidden input field that automatically updates when a date is selected. Perfect for date input fields in forms.

Form Integration Example

Select the date for your event
This field is required

Usage Examples

Basic Calendar

<c-date.calendar />

<!-- With initial value -->
<c-date.calendar value="2024-06-15" />

<!-- With custom color -->
<c-date.calendar color="secondary" />

Calendar with Header and Actions

<c-date.calendar 
  header 
  actions 
  value="2024-06-15"
  color="primary" />

Inline Calendar Form Field

<c-date.inline 
  name="birthday" 
  id="birthday"
  value=""
  required
  help_text="Enter your date of birth">
  Date of Birth
</c-date.inline>

JavaScript Integration

// Listen for date changes
document.querySelector('[data-calendar]')
  .addEventListener('calendar:change', function(event) {
    console.log('Selected date:', event.detail.formatted);
    console.log('Date object:', event.detail.date);
  });

// Programmatically set date
const calendar = document.querySelector('[data-calendar]');
calendar.materialCalendar.setValue('2024-12-25');

// Get current value
const currentDate = calendar.materialCalendar.getValue();

Calendar Attributes

Attribute
Type
Default
Description
color string "primary" Color theme: primary, secondary, tertiary
header boolean false Show date header panel
actions boolean false Show cancel/OK buttons
disabled boolean false Disable interaction
format string "%Y-%m-%d" Django date format string
value string "" Initial date value in specified format
class string "flex max-w-lg" Additional CSS classes

Inline Calendar Attributes

Attribute
Type
Default
Description
name string - Form field name for the hidden input
id string - Form field ID for the hidden input
required boolean false Mark field as required
help_text string - Helper text displayed below calendar
error string - Error message displayed below calendar
Also inherits all calendar attributes (color, format, value, disabled)

Date Format Codes

The calendar components use Django-style date format codes. Here are the supported format codes:

Code
Description
Example
%d Day of month (01-31) 01, 15, 31
%m Month (01-12) 01, 06, 12
%b Month abbreviation Jan, Jun, Dec
%Y 4-digit year 2024
%H Hour (00-23) 00, 14, 23
%I Hour (01-12) 01, 02, 12
%M Minute (00-59) 00, 30, 59
%S Second (00-59) 00, 30, 59
%p AM/PM am, pm

Common Format Examples

"%Y-%m-%d"         → 2024-06-15 (ISO format)
"%d/%m/%Y"         → 15/06/2024 (European format)
"%m/%d/%Y"         → 06/15/2024 (US format)
"%b %d, %Y"        → Jun 15, 2024 (Long format)
"%Y-%m-%d %H:%M"   → 2024-06-15 14:30 (With time)

Accessibility

The calendar components are designed with accessibility in mind, following WCAG guidelines and providing comprehensive keyboard navigation support.

Keyboard Navigation

  • Arrow Keys - Navigate between dates
  • Enter or Space - Select current date
  • Escape - Cancel selection (when actions enabled)
  • Tab - Move focus to navigation buttons
  • Click month/year header - Open year picker for fast year selection

Screen Reader Support

  • • Proper ARIA labels for navigation buttons
  • • Semantic HTML structure with appropriate roles
  • • Descriptive text for selected dates
  • • Form integration with hidden inputs for proper labeling

JavaScript API

Each calendar component exposes a JavaScript API for programmatic interaction:

Methods

// Get the calendar element
const calendar = document.querySelector('[data-calendar]');

// Get current value as formatted string
const value = calendar.materialCalendar.getValue();

// Set value from formatted string
calendar.materialCalendar.setValue('2024-12-25');

// Get current date as Date object
const date = calendar.materialCalendar.getDate();

// Set date from Date object
calendar.materialCalendar.setDate(new Date(2024, 11, 25));

Events

// Listen for date changes
calendar.addEventListener('calendar:change', function(event) {
  console.log('Date changed:', event.detail.formatted);
  console.log('Date object:', event.detail.date);
});

// Listen for cancel action (when actions enabled)
calendar.addEventListener('calendar:cancel', function(event) {
  console.log('Calendar cancelled');
});

// Listen for accept action (when actions enabled)
calendar.addEventListener('calendar:accept', function(event) {
  console.log('Date accepted:', event.detail.formatted);
});