syncfusion-react-calendars

# Implementing Syncfusion React Calendars ## Calendar The Syncfusion React **CalendarComponent** 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 (React) #### Install ```bash npm install @syncfusion/ej2-react-calendars @syncfusion/ej2-base ``` #### Basic Example (App.jsx) ```jsx import React, { useState } from 'react'; import { CalendarComponent } from '@syncfusion/ej2-react-calendars'; import '@syncfusion/ej2-base/styles/material3.css'; import '@syncfusion/ej2-calendars/styles/material3.css'; export default function App() { const [value, setValue] = useState(new Date()); const onChange = (args) => setValue(args.value || args); return ( <div style={{ padding: 20 }}> <h3>Select a date</h3> <CalendarComponent value={value} change={onChange} /> <p>Selected: {value.toDateString()}</p> </div> ); } ``` Notes: - Use the `change` event to sync selected date to React state. - Import theme CSS once (global or component-level) to style the control. ### Guidance & Patterns - **Controlled component:** keep source-of-truth in React state and update `value` via `change` event. - **Multi-selection:** use `isMultiSelection={true}` with `values` prop and `addDate()`/`removeDate()` methods. - **Programmatic navigation:** use a `ref` to call `navigateTo(view, date)` — both arguments are required (see references/getting-started-react.md). - **Date ranges:** for range selection, use DateRangePicker (separate component). The Calendar itself does not have a built-in range highlight mode. - **Accessibility:** use wrapper elements with `role="region"` and a separate `aria-live` region for announcements — these are not direct Calendar props. - **Week numbers:** enable with `weekNumber={true}` (the correct prop name). ### References Navigate to the reference that matches your current task: #### Getting Started 📄 **Read:** [references/getting-started-react.md](references/calendar-getting-started-react.md) - Installation and npm setup - React component examples - CSS/theme imports - Using refs and methods #### Date Selection 📄 **Read:** [references/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-views.md](references/calendar-calendar-views.md) - Month, Year, Decade views - Navigating between views - Initial and depth controls - Programmatic navigation #### Styling & Customization 📄 **Read:** [references/styling-customization.md](references/calendar-styling-customization.md) - Theme selection and switching - CSS class customization - Custom day cell rendering - RTL and responsive design #### Events & Methods 📄 **Read:** [references/events-methods.md](references/calendar-events-methods.md) - Event handlers (change, created, renderDayCell) - Using refs and imperative methods - Advanced renderDayCell hook - Event tracking patterns #### Accessibility & Globalization 📄 **Read:** [references/accessibility-globalization.md](references/calendar-accessibility-globalization.md) - WCAG 2.1 compliance - Keyboard navigation - ARIA attributes - Locale support and RTL - Testing for accessibility #### API Reference (Quick Lookup) 📄 **Read:** [references/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 styles. - **React state mismatch:** use the `value` prop and `change` event to keep React state in sync — do not rely on framework-specific bindings. - **Multiple date selection not working:** ensure `isMultiSelection={true}` and use `values` (not `value`) for the initial array. - **`navigateTo` not working:** the method requires two arguments — `navigateTo(view: CalendarView, date: Date)`. - **"Cannot find module":** run `npm install @syncfusion/ej2-react-calendars @syncfusion/ej2-base` and confirm `package.json`. - **Week numbers not showing:** use `weekNumber={true}` (not `showWeekNumber`). ## DatePicker The Syncfusion React **DatePickerComponent** 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 integration as a controlled React component. ### Component Overview The **DatePicker** is a Syncfusion React 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** - Controlled components, React hooks, 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 \| FormatObject | null | Display format (e.g., `"dd/MM/yyyy"`) | | `inputFormats` | string[] \| FormatObject[] | 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` | MaskPlaceholderModel | {...} | 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` | { [key: string]: string } | {} | Additional HTML attributes | | `keyConfigs` | { [key: string]: string } | null | Custom key action mappings | | `width` | number \| string | 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 | | `removeDate(dates)` | void | Removes date(s) from the values | | `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` | PreventableEventArgs \| PopupObjectArgs | Fires when the popup opens | | `close` | PreventableEventArgs \| PopupObjectArgs | 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 the user needs help with DatePicker, guide them to the appropriate reference: #### Getting Started 📄 **Read:** [references/getting-started.md](references/datepicker-getting-started.md) - Installation via npm (@syncfusion/ej2-react-calendars) - CSS theme imports (material3, bootstrap, fluent, tailwind) - Component imports and setup - Basic JSX implementation with DatePickerComponent - Functional vs class component examples - Running your first application #### Date Formats & Input 📄 **Read:** [references/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/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/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/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/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/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/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: ```jsx import React, { useState } from 'react'; import { DatePickerComponent } from '@syncfusion/ej2-react-calendars'; import '@syncfusion/ej2-base/styles/material3.css'; import '@syncfusion/ej2-buttons/styles/material3.css'; import '@syncfusion/ej2-inputs/styles/material3.css'; import '@syncfusion/ej2-popups/styles/material3.css'; import '@syncfusion/ej2-react-calendars/styles/material3.css'; export default function App() {