syncfusion-javascript-calendars

# Implementing Syncfusion JavaScript (EJ2) Calendars ## Calendar The Syncfusion EJ2 **Calendar** is a highly customizable calendar UI control that allows users to select single or multiple dates. It supports multiple views (Month, Year, Decade), navigation, week numbers, disabled dates, custom day cell rendering, localization, RTL support, and full accessibility (WCAG 2.2 compliant). ### Quick Start (TypeScript) #### Install ```bash npm install @syncfusion/ej2-calendars @syncfusion/ej2-base npm audit ``` #### Basic Example ```html <div id="calendar"></div> ``` ```typescript import { Calendar } from '@syncfusion/ej2-calendars'; const calendar = new Calendar({ value: new Date(), change: (args: any) => { console.log('Selected date:', args.value); } }); calendar.appendTo('#calendar'); ``` Notes: - Use the `change` event to respond to selected date changes. - Import theme CSS to style the control. - No React state management needed — EJ2 handles internal state. ### Guidance & Patterns - **Controlled component:** Access current value via `calendar.value` property and listen to `change` event. - **Multi-selection:** Use `isMultiSelection: true` with `values` property and `addDate()`/`removeDate()` methods. - **Programmatic navigation:** Call `navigateTo(view, date)` method — both arguments are required. - **Date ranges:** For range selection, use DateRangePicker (separate component). Calendar does not have built-in range highlight mode. - **Accessibility:** Calendar handles ARIA attributes automatically. Use wrapper elements with `role="region"` for additional context if needed. - **Week numbers:** Enable with `weekNumber: true` property. ### References Navigate to the reference that matches your current task: #### Getting Started 📄 **Read:** [references/calendar-getting-started.md](references/calendar-getting-started.md) - Installation and npm setup - TypeScript component examples - CSS/theme imports - Using methods and event handling #### Date Selection 📄 **Read:** [references/calendar-date-selection.md](references/calendar-date-selection.md) - Single date selection - Multiple dates and ranges - Min/max constraints - Disabling specific dates #### Calendar Views 📄 **Read:** [references/calendar-calendar-views.md](references/calendar-calendar-views.md) - Month, Year, Decade views - Navigating between views - Initial and depth controls - Programmatic navigation #### Styling & Customization 📄 **Read:** [references/calendar-styling-and-customization.md](references/calendar-styling-and-customization.md) - Theme selection and switching - CSS class customization - Custom day cell rendering - RTL and responsive design #### Events & Methods 📄 **Read:** [references/calendar-events-and-methods.md](references/calendar-events-and-methods.md) - Event handlers (change, created, renderDayCell) - Using methods (navigateTo, addDate, removeDate) - Advanced renderDayCell hook - Event tracking patterns #### Accessibility & Globalization 📄 **Read:** [references/calendar-accessibility-and-globalization.md](references/calendar-accessibility-and-globalization.md) - WCAG 2.1 compliance - Keyboard navigation - ARIA attributes - Locale support and RTL #### API Reference (Quick Lookup) 📄 **Read:** [references/calendar-api-reference.md](references/calendar-api-reference.md) - Props, events, methods at a glance - Common enums and types - Link to upstream docs #### Troubleshooting & Tips - **Styles not applied:** Confirm CSS imports point to `node_modules/@syncfusion/ej2-calendars/styles/` and are loaded before component initialization. - **Value not updating:** Use the `change` event to update component state — EJ2 components notify changes through events, not automatic binding. - **Multiple date selection not working:** Ensure `isMultiSelection: true` and use `values` array property for initial values. - **`navigateTo` not working:** The method requires two arguments — `navigateTo(view: CalendarView, date: Date)`. - **"Cannot find module":** Run `npm install @syncfusion/ej2-calendars @syncfusion/ej2-base` and confirm `package.json`. - **Week numbers not showing:** Use `weekNumber: true` (not `showWeekNumber`). ## DatePicker The Syncfusion EJ2 **DatePicker** provides an intuitive input control with a calendar popup for selecting a single date. It features flexible formatting, masked input, min/max date validation, strict mode, multiple input formats, custom day rendering, localization, and seamless form integration. ### Component Overview The **DatePicker** is a Syncfusion EJ2 component for date selection with powerful features: - **Calendar popup** - Visual date selection with navigation - **Flexible formatting** - Display and input formats with pattern support - **Masked input** - `enableMask` for segment-by-segment date entry with `maskPlaceholder` - **Range validation** - Min/max dates with `strictMode` automatic correction - **Multiple views** - Month, year, and decade views via `start` and `depth` properties - **Day cell customization** - Disable weekends, highlight special dates via `renderDayCell` event - **Full globalization** - 150+ cultures, RTL (`enableRtl`), locale-specific formatting, `firstDayOfWeek` - **WCAG 2.2 compliant** - Full accessibility with keyboard navigation and ARIA attributes - **Form ready** - Direct DOM binding, event-driven updates, form validation integration - **Programmatic control** - `show()`, `hide()`, `focusIn()`, `focusOut()`, `navigateTo()`, `currentView()` ### Complete API Summary #### Key Properties | Property | Type | Default | Description | |----------|------|---------|-------------| | `value` | Date | null | Selected date | | `min` | Date | 1900-01-01 | Minimum selectable date | | `max` | Date | 2099-12-31 | Maximum selectable date | | `format` | string | null | Display format (e.g., `"dd/MM/yyyy"`) | | `inputFormats` | string[] | null | Accepted input formats array | | `placeholder` | string | null | Placeholder text for the input | | `enabled` | boolean | true | Enable or disable the component | | `readonly` | boolean | false | Readonly state | | `allowEdit` | boolean | true | Allow editing the input textbox | | `strictMode` | boolean | false | Auto-correct out-of-range dates | | `showClearButton` | boolean | true | Show/hide the clear button | | `showTodayButton` | boolean | true | Show/hide today button | | `start` | CalendarView | Month | Initial view: `"Month"`, `"Year"`, `"Decade"` | | `depth` | CalendarView | Month | Deepest navigation level | | `enableMask` | boolean | false | Enable masked date input | | `maskPlaceholder` | object | {...} | Segment placeholders for masked input | | `enableRtl` | boolean | false | Right-to-left rendering | | `locale` | string | '' | Culture/locale code | | `firstDayOfWeek` | number | 0 | First day of week (0=Sunday) | | `weekNumber` | boolean | false | Show week numbers | | `weekRule` | WeekRule | FirstDay | Rule for first week of year | | `calendarMode` | CalendarType | Gregorian | Calendar type (Gregorian or Islamic) | | `dayHeaderFormat` | DayHeaderFormats | Short | Day name format in header | | `floatLabelType` | FloatLabelType | Never | Floating label behavior | | `fullScreenMode` | boolean | false | Full screen popup on mobile | | `openOnFocus` | boolean | false | Open popup on input focus | | `serverTimezoneOffset` | number | null | Server timezone offset | | `cssClass` | string | null | Custom CSS class | | `htmlAttributes` | object | {} | Additional HTML attributes | | `keyConfigs` | object | null | Custom key action mappings | | `width` | string \| number | null | Component width | | `zIndex` | number | 1000 | Popup z-index | | `enablePersistence` | boolean | false | Persist state between reloads | #### Methods | Method | Returns | Description | |--------|---------|-------------| | `show()` | void | Opens the calendar popup | | `hide()` | void | Closes the calendar popup | | `focusIn()` | void | Sets focus to the component | | `focusOut()` | void | Removes focus from the component | | `navigateTo(view, date)` | void | Navigates to a specific view and date | | `currentView()` | string | Returns the current calendar view name | | `getPersistData()` | string | Gets persisted state data | | `destroy()` | void | Destroys the component | #### Events | Event | Args Type | Description | |-------|-----------|-------------| | `change` | ChangedEventArgs | Fires when the selected date changes | | `focus` | FocusEventArgs | Fires when input gains focus | | `blur` | BlurEventArgs | Fires when input loses focus | | `open` | PopupEventArgs | Fires when the popup opens | | `close` | PopupEventArgs | Fires when the popup closes | | `cleared` | ClearedEventArgs | Fires when value is cleared | | `created` | Object | Fires when component is created | | `destroyed` | Object | Fires when component is destroyed | | `navigated` | NavigatedEventArgs | Fires when calendar view is navigated | | `renderDayCell` | RenderDayCellEventArgs | Fires when each day cell is rendered | ### Documentation & Navigation Guide When you need help with DatePicker, guide to the appropriate reference: #### Getting Started 📄 **Read:** [references/datepicker-getting-started.md](references/datepicker-getting-started.md) - Installation via npm (@syncfusion/ej2-calendars) - CSS theme imports (material3, bootstrap, fluent, tailwind) - Component imports and setup - Basic TypeScript implementation - Running your first application #### Date Formats & Input 📄 **Read:** [references/datepicker-date-formats-and-input.md](references/datepicker-date-formats-and-input.md) - Display format property and patterns (yyyy-MM-dd, dd/MM/yyyy, etc.) - Custom format specifiers (# and 0 patterns) - Input formats for flexible date entry (accepting multiple formats) - Format examples with real-world scenarios - Parsing and converting user input automatically - Culture-based default formatting #### Date Range & Validation 📄 **Read:** [references/datepicker-date-range-and-validation.md](references/datepicker-date-range-and-validation.md) - Min and max date properties for range restriction - Range validation and error states - strictMode for automatic out-of-range correction - Out-of-range behavior and error handling - Disabling dates outside valid range - Edge cases and gotchas #### Date Views & Navigation 📄 **Read:** [references/datepicker-date-views-and-navigation.md](references/datepicker-date-views-and-navigation.md) - Start property (month, year, decade initial view) - Depth property for restricting view levels - Calendar navigation and user interactions - Month and year selection shortcuts - Navigating between different views - Default behavior and best practices #### Customization & Styling 📄 **Read:** [references/datepicker-customization-and-styling.md](references/datepicker-customization-and-styling.md) - CSS classes for styling (e-datepicker, e-calendar, e-day, etc.) - renderDayCell event for day customization - Disabling specific dates and weekends - Placeholder, disabled, and readonly states - Custom CSS and theme customization - Day cell appearance and behavior #### Globalization & Localization 📄 **Read:** [references/datepicker-globalization-and-localization.md](references/datepicker-globalization-and-localization.md) - Culture and locale configuration (German, French, Arabic, etc.) - Loading CLDR data for internationalization - Date format by culture (different countries, different formats) - Locale text customization (today button, placeholder) - Right-to-Left (RTL) support for Arabic, Hebrew, Urdu - Week start day by culture - Number formatting and calendar adjustments #### Accessibility & Keyboard Navigation 📄 **Read:** [references/datepicker-accessibility-and-keyboard.md](references/datepicker-accessibility-and-keyboard.md) - WCAG 2.2 compliance and accessibility standards - Keyboard navigation shortcuts (Alt+Down, arrow keys, Esc) - ARIA attributes (aria-expanded, aria-disabled, aria-activedescendant) - Screen reader support and announcements - Focus management and visible focus indicators - Color contrast and visual accessibility - Mobile device support #### Date Masking & Advanced Validation 📄 **Read:** [references/datepicker-date-masking-and-strict-mode.md](references/datepicker-date-masking-and-strict-mode.md) - `enableMask` property for structured segment-by-segment date input - `maskPlaceholder` for custom segment placeholder text - Date masking patterns for input guidance - `strictMode` property behavior and enforcement - Date parsing rules and validation logic - Input validation and format enforcement - Edge cases (leap years, month boundaries, etc.) - Troubleshooting common validation issues - Best practices for date input ### Quick Start Example Here's a minimal working example to get started: ```html <input id="datepicker" type="text" /> ``` ```typescript import { DatePicker } from '@syncfusion/ej2-calendars'; const datepicker = new DatePicker({ value: new Date(), change: (e: any) => { console.log('Selected date:', e.value); }, placeholder: 'Enter date' }); datepicker.appendTo('#datepicker'); ``` **Key points:** - Import `DatePicker` from `@syncfusion/ej2-calendars` - Create an instance with `new DatePicker({...})` - Use `appendTo()` to render in a target DOM element - Use `change` event to react to date selection - DatePicker opens a calendar popup on click or Alt+Down arrow ## DateRangePicker The Syncfusion EJ2 **DateRangePicker** enables users to select a start and end date range with built-in support for presets, validation, custom formatting, separator configuration, full-screen mobile mode, and advanced range constraints (minDays, maxDays, min, max). ### Documentation Navigation Guide #### Getting Started