syncfusion-react-datepicker

Implementing DatePicker

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

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

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

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

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

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

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

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

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:

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() {
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <div style={{ padding: '20px' }}>
      <h3>Select a Date</h3>
      <DatePickerComponent
        value={selectedDate}
        change={(e) => setSelectedDate(e.value)}
        placeholder="Enter date"
      />
      <p>Selected: {selectedDate?.toDateString()}</p>
    </div>
  );
}

Key points:

Import DatePickerComponent from @syncfusion/ej2-react-calendars
Import all required CSS themes (base, buttons, inputs, popups, calendars)
Use value prop for the current date (can be null or Date object)
Use change event (not onChange) to update React state — this is the Syncfusion event name
DatePicker opens a calendar popup on click or Alt+Down arrow

Common Patterns

1. Date Range Picker (Min/Max Dates)

<DatePickerComponent
  value={new Date()}
  min={new Date(2026, 0, 1)}
  max={new Date(2026, 11, 31)}
  placeholder="Select a date in 2026"
/>

2. Custom Date Format

<DatePickerComponent
  value={new Date()}
  format="dd/MM/yyyy"
  placeholder="DD/MM/YYYY"
/>

3. Multiple Accepted Input Formats

<DatePickerComponent
  value={new Date()}
  format="yyyy-MM-dd"
  inputFormats={['dd/MM/yyyy', 'yyyy-MM-dd', 'yyyyMMdd']}
  placeholder="Enter date (dd/MM/yyyy or yyyy-MM-dd)"
/>

4. Year/Decade View for Birth Date Selection

<DatePickerComponent
  value={new Date()}
  start="Decade"
  depth="Year"
  placeholder="Select year"
/>

5. Disable Weekends

<DatePickerComponent
  value={new Date()}
  renderDayCell={(args) => {
    if ((args.date.getDay()) === 0 || (args.date.getDay()) === 6) {
      args.isDisabled = true;
    }
  }}
  placeholder="Weekdays only"
/>

6. Controlled Component in React Form

const [date, setDate] = useState(null);

<DatePickerComponent
  value={date}
  change={(e) => setDate(e.value)}
  format="yyyy-MM-dd"
  strictMode={true}
  placeholder="Enter date"
/>

7. German Culture with RTL Support

<DatePickerComponent
  locale="de"
  enableRtl={false}
  firstDayOfWeek={1}
  value={new Date()}
  placeholder="Datum eingeben"
/>

8. Masked Date Input

<DatePickerComponent
  enableMask={true}
  format="MM/dd/yyyy"
  maskPlaceholder={{ day: 'DD', month: 'MM', year: 'YYYY' }}
  placeholder="Select a date"
/>

9. Programmatic Control

import { useRef } from 'react';

const datePickerRef = useRef(null);

// Open calendar
datePickerRef.current.show();

// Close calendar
datePickerRef.current.hide();

// Focus
datePickerRef.current.focusIn();

// Get current view
const view = datePickerRef.current.currentView(); // "Month" | "Year" | "Decade"

// Navigate to specific view
datePickerRef.current.navigateTo('Year', new Date(2026, 0, 1));

<DatePickerComponent ref={datePickerRef} value={new Date()} />

10. Handle All Key Events

<DatePickerComponent
  value={new Date()}
  change={(e) => console.log('Changed:', e.value)}
  focus={(e) => console.log('Focused')}
  blur={(e) => console.log('Blurred')}
  open={(e) => console.log('Opened')}
  close={(e) => console.log('Closed')}
  cleared={(e) => console.log('Cleared')}
  navigated={(e) => console.log('Navigated to view:', e.view)}
  renderDayCell={(args) => {
    // Disable weekends
    if (args.date.getDay() === 0 || args.date.getDay() === 6) {
      args.isDisabled = true;
    }
  }}
/>