react-calendar-datetime-picker
A modern, fast and small calendar for React with comprehensive support for Gregorian and Jalali (Persian) calendar systems.
Full Documentation Website - Complete guide with examples, API reference, and more
Features
Core Capabilities
- Dual Calendar Support - Native support for both Gregorian and Jalali (Persian) calendars with automatic locale handling
- Flexible Selection Modes - Single date, date range, multi-date, and week selection modes
- Time Selection - Full time picker integration with 12-hour and 24-hour formats
- TypeScript Support - Comprehensive type definitions with improved IntelliSense and type safety
- Internationalization (i18n) - Full locale support for English, Persian, German, Spanish, and French with RTL support
- Dark Mode - Built-in dark theme with automatic detection
- Accessibility - Full keyboard navigation, ARIA labels, and WCAG 2.1 Level AA compliance
Advanced Features
- Preset Date Ranges - Built-in preset buttons for common ranges with custom preset support
- Advanced Constraints - Minimum/maximum dates, disabled dates, and custom validation functions
- Multiple Months Display - Display multiple calendar months side by side
- Week Customization - Customize week start day, weekend highlighting, and weekday names
- CSS Variables Support - Easy theming with CSS custom properties
- Custom Trigger Elements - Use any React element as a trigger for the date picker
- Input-less Mode - Display standalone calendars without input fields
- Smart Modal Positioning - Intelligent modal positioning with automatic viewport adjustment
- Comprehensive Error Handling - Robust error handling with onError callback for validation errors
- Extended Utility Functions - Comprehensive date manipulation utilities and calendar conversions
Installation
npm install react-calendar-datetime-picker
# or
yarn add react-calendar-datetime-picker
# or
pnpm add react-calendar-datetime-pickerQuick Start
import { DtPicker } from 'react-calendar-datetime-picker'
import 'react-calendar-datetime-picker/style.css'
function App() {
const [date, setDate] = useState()
return (
<DtPicker
initValue={date}
onChange={setDate}
calendarSystem='gregorian'
locale='en'
/>
)
}New Features in v2.x
Version 2.x brings significant improvements and new capabilities:
Enhanced TypeScript Support
- Better type definitions and improved IntelliSense
- Stricter type checking for a more robust development experience
Comprehensive onChange Output
- Enhanced onChange callback provides three parameters: normalized Day object, JavaScript Date (always Gregorian), and formatted string
Improved Performance
- Optimized rendering and memoization
- Reduced bundle size for faster loading
Enhanced Customization
- Custom icons, labels, translations, and CSS classes
- Complete control over component styling
Rich Event System
- Comprehensive callback system for date selection, navigation, and user interactions
Better Accessibility
- Full keyboard navigation support
- ARIA labels and focus management
- Screen reader support
Smart Modal Positioning
- Intelligent modal positioning that automatically adjusts based on viewport space
- Handles RTL/LTR layouts and dynamic repositioning
Comprehensive Error Handling & Validation
- Robust error handling system with onError callback
- Handles invalid dates, constraint violations, and provides detailed error information
For a complete list of features and migration guide, visit the documentation website.
Keywords
This library supports:
Core Technologies
- React - Built with modern React patterns (Hooks, Functional Components)
- TypeScript - Full TypeScript support with comprehensive type definitions
- Calendar - Full-featured calendar component with month/year navigation
Selection Types
- Date Picker - Interactive date selection with input field integration
- DateTime Picker - Combined date and time selection with 12/24-hour formats
- Time Picker - Full time selection with hours and minutes
- Date Range - Select start and end dates for range-based selections
- Multi-Date Selection - Select multiple individual dates
- Week Selection - Select entire weeks with customizable start days
Calendar Systems
- Persian - Native Persian (Farsi) locale support with RTL layout
- Jalali - Complete Jalali (Persian) calendar system implementation
- Gregorian - Standard Gregorian calendar system support
Internationalization & Localization
- i18n - Full internationalization support for multiple languages
- RTL - Right-to-left layout support for Persian and other RTL languages
- Locale - Support for English, Persian, German, Spanish, and French locales
- Localization - Customizable translations and regional formatting
UI & UX Features
- Dark Mode - Built-in dark theme with automatic detection
- Accessibility - WCAG 2.1 Level AA compliant with keyboard navigation and ARIA labels
- Modal - Smart modal positioning with automatic viewport adjustment
- Customization - Extensive customization options for styling, icons, and labels
- Theming - CSS variables support for easy theme integration
- Preset Ranges - Built-in preset buttons for common date ranges
Advanced Features
- Constraints - Minimum/maximum dates, disabled dates, and custom validation
- Validation - Comprehensive error handling and validation system
- Utilities - Extended date manipulation and calendar conversion utilities
- Standalone Calendar - Input-less mode for embedded calendar displays
Development
# Install dependencies
pnpm install
# Run development server
pnpm run dev:examples
# Build library
pnpm run build
# Run tests
pnpm test
# Type checking
pnpm run typecheck
# Linting
pnpm run lintDocumentation
User Documentation
- Website - Full documentation website with examples
Developer Documentation
- Architecture - Project architecture and structure
- Development Guide - Development workflow and guidelines
- Deployment Guide - Deployment guide for npm and GitHub Pages
- Monorepo Setup - Monorepo structure and configuration
- Version Management - Version management and publishing
See docs-dev/README.md for complete documentation index.