syncfusion-react-daterangepicker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React DateRangePicker Component

实现Syncfusion React DateRangePicker组件

The Syncfusion React DateRangePicker component provides an intuitive way to select a date range with support for preset ranges, date validation, multiple date formats, keyboard navigation, and mobile-optimized full-screen mode.

Syncfusion React DateRangePicker组件提供了直观的日期范围选择能力，支持预设范围、日期校验、多种日期格式、键盘导航以及针对移动端优化的全屏模式。

Documentation Navigation Guide

文档导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation via npm (@syncfusion/ej2-react-calendars)
CSS imports and theme configuration
Basic DateRangePicker implementation
Class component vs functional component setup
Component initialization and structure
Running development server
Common troubleshooting

📄 阅读： references/getting-started.md

通过npm安装（@syncfusion/ej2-react-calendars）
CSS导入与主题配置
基础DateRangePicker实现
类组件与函数式组件的配置方式
组件初始化与结构
启动开发服务
常见问题排查

Date Range Selection

日期范围选择

📄 Read: references/date-range-selection.md

Start and end date properties
Date range validation patterns
Minimum and maximum date constraints
Disabled dates configuration
Date range presets (Last 7 days, Last 30 days, etc.)
Value binding and two-way updates
Read-only and disabled states
Placeholder and labels

📄 阅读： references/date-range-selection.md

开始与结束日期属性
日期范围校验规则
最小与最大日期限制
禁用日期配置
日期范围预设（最近7天、最近30天等）
值绑定与双向更新
只读与禁用状态
占位符与标签

Date Range Formatting

日期范围格式化

📄 Read: references/date-range-formatting.md

Date format string options (MM/dd/yyyy, dd-MMM-yyyy, etc.)
Display format vs input format
Locale-based date formatting
Custom separator between start and end dates
Float label types (Never, Always, Auto)
Placeholder text customization
htmlAttributes for DOM attributes

📄 阅读： references/date-range-formatting.md

日期格式字符串选项（MM/dd/yyyy、dd-MMM-yyyy等）
展示格式与输入格式的区别
基于地区的日期格式化
开始与结束日期的自定义分隔符
浮动标签类型（Never、Always、Auto）
占位符文本自定义
用于DOM属性的htmlAttributes

Events and Methods

事件与方法

📄 Read: references/events-and-methods.md

Event handlers (change, open, close, blur, focus, select)
Event argument structures
Methods (show, hide, focusIn, focusOut, reset, destroy)
Imperative control with useRef
Lifecycle events (created, destroyed)
Event patterns and best practices
Clearing values and state reset
DateRangeSelectingEvent and ChangedEventArgs

📄 阅读： references/events-and-methods.md

事件处理函数（change、open、close、blur、focus、select）
事件参数结构
方法（show、hide、focusIn、focusOut、reset、destroy）
结合useRef的命令式控制
生命周期事件（created、destroyed）
事件使用模式与最佳实践
清空值与状态重置
DateRangeSelectingEvent与ChangedEventArgs

Customization and Styling

自定义与样式

📄 Read: references/customization-and-styling.md

CSS class customization with cssClass
Theme options (Material, Bootstrap, Fluent, Tailwind, Fabric)
Full-screen mode for mobile devices
RTL (right-to-left) language support
Preset ranges customization
Z-index management
Width and height configuration
Accessibility features and ARIA attributes

📄 阅读： references/customization-and-styling.md

通过cssClass自定义CSS类
主题选项（Material、Bootstrap、Fluent、Tailwind、Fabric）
移动端全屏模式
RTL（从右到左）语言支持
预设范围自定义
Z-index管理
宽高配置
无障碍功能与ARIA属性

API Reference

API参考

📄 Read: references/api-reference.md

Complete properties list (35+ properties)
All methods with signatures (8 methods)
All events with event arguments (12 events)
Type definitions and interfaces
Default values and constraints
Use cases for each property and method

📄 阅读： references/api-reference.md

完整属性列表（35+属性）
所有带签名的方法（8个方法）
所有带参数的事件（12个事件）
类型定义与接口
默认值与约束
每个属性和方法的使用场景

Advanced Patterns

高级模式

📄 Read: references/advanced-patterns.md

Form submission with date range validation
Keyboard shortcuts and key navigation
Server timezone offset handling
Persistence and localStorage
Multi-component integration (start/end date binding)
Performance optimization with lazy loading
Error handling and validation patterns
Complex date range scenarios (fiscal years, quarters)

📄 阅读： references/advanced-patterns.md

带日期范围校验的表单提交
键盘快捷键与导航
服务端时区偏移处理
持久化与localStorage
多组件集成（开始/结束日期绑定）
懒加载性能优化
错误处理与校验模式
复杂日期范围场景（财年、季度）

Quick Start

快速开始

tsx

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-buttons/styles/material3.css';
import '@syncfusion/ej2-lists/styles/material3.css';
import '@syncfusion/ej2-inputs/styles/material3.css';
import '@syncfusion/ej2-popups/styles/material3.css';
import '@syncfusion/ej2-calendars/styles/material3.css';

function App() {
  const [selectedRange, setSelectedRange] = React.useState<[Date, Date] | null>(null);

  const handleDateRangeChange = (e: any) => {
    setSelectedRange([e.startDate, e.endDate]);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h2>Select Date Range</h2>
      <DateRangePickerComponent
        id="daterangepicker"
        placeholder="Select a range"
        change={handleDateRangeChange}
      />
      {selectedRange && (
        <p>
          Selected: {selectedRange[0]?.toLocaleDateString()} - {selectedRange[1]?.toLocaleDateString()}
        </p>
      )}
    </div>
  );
}

export default App;

tsx

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-buttons/styles/material3.css';
import '@syncfusion/ej2-lists/styles/material3.css';
import '@syncfusion/ej2-inputs/styles/material3.css';
import '@syncfusion/ej2-popups/styles/material3.css';
import '@syncfusion/ej2-calendars/styles/material3.css';

function App() {
  const [selectedRange, setSelectedRange] = React.useState<[Date, Date] | null>(null);

  const handleDateRangeChange = (e: any) => {
    setSelectedRange([e.startDate, e.endDate]);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h2>Select Date Range</h2>
      <DateRangePickerComponent
        id="daterangepicker"
        placeholder="Select a range"
        change={handleDateRangeChange}
      />
      {selectedRange && (
        <p>
          Selected: {selectedRange[0]?.toLocaleDateString()} - {selectedRange[1]?.toLocaleDateString()}
        </p>
      )}
    </div>
  );
}

export default App;

Common Patterns

常见模式

Pattern 1: Date Range with Preset Options

模式1：带预设选项的日期范围

tsx

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';

function ReportingDashboard() {
  const [dateRange, setDateRange] = React.useState<[Date, Date] | null>(null);

  const getDateRangePresets = () => {
    const today = new Date();
    const yesterday = new Date(today);
    yesterday.setDate(today.getDate() - 1);
    
    const last7Days = new Date(today);
    last7Days.setDate(today.getDate() - 7);
    
    const last30Days = new Date(today);
    last30Days.setDate(today.getDate() - 30);
    
    const thisMonth = new Date(today.getFullYear(), today.getMonth(), 1);
    const lastMonth = new Date(today.getFullYear(), today.getMonth(), 0);

    return [
      { text: 'Today', value: [today, today] },
      { text: 'Yesterday', value: [yesterday, yesterday] },
      { text: 'Last 7 Days', value: [last7Days, today] },
      { text: 'Last 30 Days', value: [last30Days, today] },
      { text: 'This Month', value: [thisMonth, today] },
      { text: 'Last Month', value: [new Date(today.getFullYear(), today.getMonth() - 1, 1), lastMonth] },
    ];
  };

  const handlePresetClick = (start: Date, end: Date) => {
    setDateRange([start, end]);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h3>Analytics Report</h3>
      <DateRangePickerComponent
        id="daterangepicker"
        placeholder="Select report date range"
        startDate={dateRange?.[0]}
        endDate={dateRange?.[1]}
        change={(e: any) => setDateRange([e.startDate, e.endDate])}
      />
      
      <div style={{ marginTop: '15px' }}>
        {getDateRangePresets().map((preset) => (
          <button
            key={preset.text}
            onClick={() => handlePresetClick(preset.value[0], preset.value[1])}
            style={{ marginRight: '10px', padding: '5px 10px' }}
          >
            {preset.text}
          </button>
        ))}
      </div>
    </div>
  );
}

export default ReportingDashboard;

tsx

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';

function ReportingDashboard() {
  const [dateRange, setDateRange] = React.useState<[Date, Date] | null>(null);

  const getDateRangePresets = () => {
    const today = new Date();
    const yesterday = new Date(today);
    yesterday.setDate(today.getDate() - 1);
    
    const last7Days = new Date(today);
    last7Days.setDate(today.getDate() - 7);
    
    const last30Days = new Date(today);
    last30Days.setDate(today.getDate() - 30);
    
    const thisMonth = new Date(today.getFullYear(), today.getMonth(), 1);
    const lastMonth = new Date(today.getFullYear(), today.getMonth(), 0);

    return [
      { text: 'Today', value: [today, today] },
      { text: 'Yesterday', value: [yesterday, yesterday] },
      { text: 'Last 7 Days', value: [last7Days, today] },
      { text: 'Last 30 Days', value: [last30Days, today] },
      { text: 'This Month', value: [thisMonth, today] },
      { text: 'Last Month', value: [new Date(today.getFullYear(), today.getMonth() - 1, 1), lastMonth] },
    ];
  };

  const handlePresetClick = (start: Date, end: Date) => {
    setDateRange([start, end]);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h3>Analytics Report</h3>
      <DateRangePickerComponent
        id="daterangepicker"
        placeholder="Select report date range"
        startDate={dateRange?.[0]}
        endDate={dateRange?.[1]}
        change={(e: any) => setDateRange([e.startDate, e.endDate])}
      />
      
      <div style={{ marginTop: '15px' }}>
        {getDateRangePresets().map((preset) => (
          <button
            key={preset.text}
            onClick={() => handlePresetClick(preset.value[0], preset.value[1])}
            style={{ marginRight: '10px', padding: '5px 10px' }}
          >
            {preset.text}
          </button>
        ))}
      </div>
    </div>
  );
}

export default ReportingDashboard;

Pattern 2: Date Range with Validation

模式2：带校验的日期范围

tsx

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function BookingForm() {
  const [dateRange, setDateRange] = React.useState<[Date, Date] | null>(null);
  const [validationError, setValidationError] = React.useState<string>('');

  const minDate = new Date();
  const maxDate = new Date();
  maxDate.setDate(maxDate.getDate() + 90); // 90 days from now

  const handleDateRangeChange = (e: any) => {
    setValidationError('');
    
    if (!e.startDate || !e.endDate) {
      return;
    }

    const start = new Date(e.startDate);
    const end = new Date(e.endDate);

    // Validation checks
    if (start > end) {
      setValidationError('Start date must be before end date');
      return;
    }

    const daysDifference = (end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24);
    if (daysDifference > 30) {
      setValidationError('Date range cannot exceed 30 days');
      return;
    }

    setDateRange([start, end]);
  };

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (dateRange && !validationError) {
      console.log('Booking dates:', {
        checkIn: dateRange[0].toLocaleDateString(),
        checkOut: dateRange[1].toLocaleDateString(),
      });
    }
  };

  return (
    <form onSubmit={handleSubmit} style={{ padding: '20px', maxWidth: '500px' }}>
      <h3>Book Your Stay</h3>
      
      <label style={{ display: 'block', marginBottom: '8px' }}>
        Select Check-in and Check-out Dates (Max 30 days)
      </label>
      
      <DateRangePickerComponent
        id="daterangepicker"
        placeholder="Select check-in and check-out"
        min={minDate}
        max={maxDate}
        startDate={dateRange?.[0]}
        endDate={dateRange?.[1]}
        change={handleDateRangeChange}
        style={{ width: '100%', marginBottom: '8px' }}
      />

      {validationError && (
        <div style={{ color: 'red', marginBottom: '10px', fontSize: '14px' }}>
          ⚠️ {validationError}
        </div>
      )}

      <ButtonComponent 
        type="submit" 
        isPrimary={true} 
        disabled={!dateRange || !!validationError}
      >
        Book Now
      </ButtonComponent>
    </form>
  );
}

export default BookingForm;

tsx

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function BookingForm() {
  const [dateRange, setDateRange] = React.useState<[Date, Date] | null>(null);
  const [validationError, setValidationError] = React.useState<string>('');

  const minDate = new Date();
  const maxDate = new Date();
  maxDate.setDate(maxDate.getDate() + 90); // 90 days from now

  const handleDateRangeChange = (e: any) => {
    setValidationError('');
    
    if (!e.startDate || !e.endDate) {
      return;
    }

    const start = new Date(e.startDate);
    const end = new Date(e.endDate);

    // Validation checks
    if (start > end) {
      setValidationError('Start date must be before end date');
      return;
    }

    const daysDifference = (end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24);
    if (daysDifference > 30) {
      setValidationError('Date range cannot exceed 30 days');
      return;
    }

    setDateRange([start, end]);
  };

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (dateRange && !validationError) {
      console.log('Booking dates:', {
        checkIn: dateRange[0].toLocaleDateString(),
        checkOut: dateRange[1].toLocaleDateString(),
      });
    }
  };

  return (
    <form onSubmit={handleSubmit} style={{ padding: '20px', maxWidth: '500px' }}>
      <h3>Book Your Stay</h3>
      
      <label style={{ display: 'block', marginBottom: '8px' }}>
        Select Check-in and Check-out Dates (Max 30 days)
      </label>
      
      <DateRangePickerComponent
        id="daterangepicker"
        placeholder="Select check-in and check-out"
        min={minDate}
        max={maxDate}
        startDate={dateRange?.[0]}
        endDate={dateRange?.[1]}
        change={handleDateRangeChange}
        style={{ width: '100%', marginBottom: '8px' }}
      />

      {validationError && (
        <div style={{ color: 'red', marginBottom: '10px', fontSize: '14px' }}>
          ⚠️ {validationError}
        </div>
      )}

      <ButtonComponent 
        type="submit" 
        isPrimary={true} 
        disabled={!dateRange || !!validationError}
      >
        Book Now
      </ButtonComponent>
    </form>
  );
}

export default BookingForm;