syncfusion-angular-calendars

What this skill does

# Implementing Syncfusion Angular Calendars

## Calendars

A comprehensive guide for implementing the Syncfusion Essential JS 2 Calendar component in Angular applications. Learn to create date pickers, manage calendar views, handle events, and customize styling.

### Calendar Overview

The Syncfusion Angular Calendar component is a date selection widget that provides:

- **Multiple calendar views:** Month (default), Year, and Decade views with smooth navigation
- **Date selection modes:** Single date or multiple dates with `isMultiSelection` property
- **Navigation control:** `navigateTo()` method for programmatic view switching
- **Date manipulation methods:** `addDate()` and `removeDate()` for multi-selection management
- **Comprehensive event system:** change, created, navigated, renderDayCell, destroyed events
- **Localization support:** Locale-specific formatting, day header formats, first day of week
- **Accessibility:** Full WCAG 2.2 compliance, keyboard navigation, RTL support
- **Rich customization:** CSS classes, custom rendering, day cell customization
- **Persistence:** Optional state persistence across page reloads

**Package:** `@syncfusion/ej2-angular-calendars`

### Documentation Navigation

Read the following references based on your specific needs:

#### Getting Started
📄 **Read:** [references/getting-started.md](references/calendar-getting-started.md)
- Package installation and module setup
- CSS theme imports and dependencies
- Basic calendar implementation
- Component initialization in Angular
- Running and testing setup

#### Calendar Views
📄 **Read:** [references/calendar-views.md](references/calendar-views.md)
- Month view (default display)
- Year view implementation
- Decade view implementation
- View navigation and transitions
- `start` property usage
- `depth` property for restricting views

#### Date Selection
📄 **Read:** [references/date-selection.md](references/calendar-date-selection.md)
- Single date selection
- Multiple date selection (`isMultiSelection`)
- `value` property for single dates
- `values` array for multiple dates
- Min/max date constraints
- Date range validation

#### Events & Methods
📄 **Read:** [references/events-and-methods.md](references/calendar-events-and-methods.md)
- Event handlers (change, created, navigated, renderDayCell, destroyed)
- `addDate()` method for multi-selection
- `removeDate()` method for multi-selection
- `navigateTo()` for programmatic navigation
- `currentView()` to get active view
- `getPersistData()` to retrieve persistence data
- `destroy()` to destroy the calendar widget
- RenderDayCell for custom day styling

#### Calendar Navigation
📄 **Read:** [references/calendar-navigation.md](references/calendar-navigation.md)
- Month navigation controls
- Year and Decade view switching
- Today button (`showTodayButton`)
- `firstDayOfWeek` property
- Week number display (`weekNumber`)
- Keyboard shortcuts and navigation

#### Accessibility & Globalization
📄 **Read:** [references/accessibility-and-globalization.md](references/calendar-accessibility-and-globalization.md)
- WCAG 2.2 and Section 508 compliance
- WAI-ARIA attributes and roles
- Keyboard navigation (arrows, enter, spacebar)
- Screen reader compatibility
- Localization (locale property)
- Day header formats (Short, Narrow, Abbreviated, Wide)
- RTL (Right-to-Left) support

#### Styling & Customization
📄 **Read:** [references/styling-and-customization.md](references/calendar-styling-and-customization.md)
- CSS class customization (.e-calendar, .e-day-cell, .e-selected)
- Theme selection (Material, Bootstrap, Tailwind, Fabric)
- Dark mode implementation
- Custom day cell styling via renderDayCell
- Disabled dates styling
- Hover and focus states

#### API Reference
📄 **Read:** [references/api-reference.md](references/calendar-api-reference.md)
- Complete property reference (value, values, isMultiSelection, min, max, start, depth, showTodayButton, locale, dayHeaderFormat, weekNumber, weekRule, firstDayOfWeek, cssClass, enableRtl, enabled, calendarMode, keyConfigs, enablePersistence, serverTimezoneOffset)
- All method signatures with examples (addDate, removeDate, navigateTo, currentView, getPersistData, destroy)
- Event argument types (ChangedEventArgs, NavigatedEventArgs, RenderDayCellEventArgs)
- Key configurations for keyboard shortcuts
- Calendar modes (Gregorian, Islamic)
- Return types and descriptions

### Quick Start Example

```typescript
// app.component.ts
import { Component } from '@angular/core';
import { ChangedEventArgs } from '@syncfusion/ej2-calendars';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Single date selection
  selectedDate: Date = new Date();
  
  // Multiple date selection
  selectedDates: Date[] = [
    new Date(2026, 2, 15),
    new Date(2026, 2, 20),
    new Date(2026, 2, 25)
  ];
  
  // Calendar configuration
  minDate: Date = new Date(2020, 0, 1);
  maxDate: Date = new Date(2030, 11, 31);
  
  // Event handler
  onCalendarChange(args: ChangedEventArgs): void {
    console.log('Selected date:', args.value);
  }
}
```

```html
<!-- app.component.html -->
<div style="padding: 20px; font-family: Arial, sans-serif;">
  <h2>Single Date Selection</h2>
  <ejs-calendar 
    [(ngModel)]="selectedDate"
    [min]="minDate"
    [max]="maxDate"
    (change)="onCalendarChange($event)">
  </ejs-calendar>
  <p>Selected: {{ selectedDate | date:'medium' }}</p>

  <h2>Multiple Date Selection</h2>
  <ejs-calendar 
    [(ngModel)]="selectedDates"
    [isMultiSelection]="true"
    [showTodayButton]="true">
  </ejs-calendar>
  <p>Selected dates: {{ selectedDates.length }} dates</p>
</div>
```

```css
/* app.component.css */
@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-calendars/styles/material3.css';

:host ::ng-deep .e-calendar {
  margin: 20px 0;
}

:host ::ng-deep .e-selected {
  background-color: #3f51b5;
  color: white;
}
```

### Common Patterns

#### Pattern 1: Custom Date Range (Two Calendar Instances)

The Calendar component does not have built-in range selection. Use two separate Calendar instances with `min`/`max` constraints and the `change` event to implement a custom date range picker:

```typescript
export class AppComponent {
  startDate: Date = new Date();
  endDate: Date = new Date();
  
  onStartDateChange(args: ChangedEventArgs): void {
    this.startDate = args.value;
    // Ensure end date is not before start date
    if (this.endDate < this.startDate) {
      this.endDate = this.startDate;
    }
  }
  
  onEndDateChange(args: ChangedEventArgs): void {
    this.endDate = args.value;
  }
  
  getDaysInRange(): number {
    const timeDiff = this.endDate.getTime() - this.startDate.getTime();
    return Math.ceil(timeDiff / (1000 * 3600 * 24)) + 1;
  }
}
```

```html
<!-- Two separate Calendar instances for range selection -->
<ejs-calendar [(ngModel)]="startDate" (change)="onStartDateChange($event)"></ejs-calendar>
<ejs-calendar [(ngModel)]="endDate" [min]="startDate" (change)="onEndDateChange($event)"></ejs-calendar>
```

#### Pattern 2: Calendar with Disabled Dates

Disable specific dates (weekends, holidays) using renderDayCell event:

```typescript
export class AppComponent {
  holidays: Date[] = [
    new Date(2026, 11, 25), // Christmas
    new Date(2026, 0, 1),   // New Year
  ];
  
  onRenderDayCell(args: RenderDayCellEventArgs): void {
    // Disable weekends
    if (args.date.getDay() === 0 || args.date.getDay() === 6) {
      args.isDisabled = true;
    }
    
    // Disable holidays
    if (this.isHoliday(args.date)) {
      args.isDisabled = true;
    }
  }
  
  private isHoliday(date: Date): boolean {
    return this.holidays.some(holiday => 
      holiday.toDateString() === date.toDateString()
    );
  }
}
```

#### Pattern 3: Multi-Selection with Add/Remove

Manage multiple selected dates programmatically: