# react-calendar-datetime-picker

> A modern, fast and small calendar for React with English and Persian (Jalali) support

Latest version **2.0.0** (published 2026-01-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-calendar-datetime-picker
pnpm add react-calendar-datetime-picker
yarn add react-calendar-datetime-picker
bun add react-calendar-datetime-picker
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-01-24 |
| First published | 2021-01-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 852.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 71 |
| Author | MehdiNasiri |
| Maintainers | mehdinasiri |
| Keywords | react, calendar, date-picker, datetime-picker, persian, jalali, gregorian, typescript |

## Links

- npm: https://www.npmjs.com/package/react-calendar-datetime-picker
- Repository: https://github.com/mehdi-nasiri-jahroodi/react-calendar-datetime-picker
- Homepage: https://mehdi-nasiri-jahroodi.github.io/react-calendar-datetime-picker/
- Issues: https://github.com/mehdi-nasiri-jahroodi/react-calendar-datetime-picker/issues
- npm.io page: https://npm.io/package/react-calendar-datetime-picker

## Dependencies (1)

- [jalaali-js](https://npm.io/package/jalaali-js.md) ^1.2.8

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2026-01-24
- 2.0.0-beta.3 (beta) — 2025-12-18
- 2.0.0-rc.0 — 2025-12-27
- 2.0.0-beta.2 — 2025-12-17
- 2.0.0-beta.1 — 2025-12-15
- 2.0.0-beta.0 — 2025-12-10
- 1.7.5 — 2025-02-23
- 1.7.4 — 2023-09-25
- 1.7.3 — 2023-09-25
- 1.7.2 — 2023-09-25
- 1.7.1 — 2023-09-21
- 1.7.0 — 2023-09-19
- 1.6.3 — 2022-05-16
- 1.6.2 — 2022-02-14
- 1.6.1 — 2022-02-14
- … 27 more at https://npm.io/package/react-calendar-datetime-picker/versions

## README

# react-calendar-datetime-picker

![Calendar Preview](./docs/public/image/react-datetime-picker.png)

A modern, fast and small calendar for React with comprehensive support for Gregorian and Jalali (Persian) calendar systems.

📚 **[Full Documentation Website](https://mehdi-nasiri-jahroodi.github.io/react-calendar-datetime-picker/)** - 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

```bash
npm install react-calendar-datetime-picker
# or
yarn add react-calendar-datetime-picker
# or
pnpm add react-calendar-datetime-picker
```

## Quick Start

```tsx
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](https://mehdi-nasiri-jahroodi.github.io/react-calendar-datetime-picker/).

## 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

```bash
# 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 lint
```

## Documentation

### User Documentation

- **[Website](https://mehdi-nasiri-jahroodi.github.io/react-calendar-datetime-picker/)** - Full documentation website with examples

### Developer Documentation

- **[Architecture](./docs-dev/ARCHITECTURE.md)** - Project architecture and structure
- **[Development Guide](./docs-dev/DEVELOPMENT.md)** - Development workflow and guidelines
- **[Deployment Guide](./docs-dev/DEPLOYMENT.md)** - Deployment guide for npm and GitHub Pages
- **[Monorepo Setup](./docs-dev/MONOREPO.md)** - Monorepo structure and configuration
- **[Version Management](./docs-dev/VERSIONING.md)** - Version management and publishing

See [docs-dev/README.md](./docs-dev/README.md) for complete documentation index.

## License

MIT © [mehdi-nasiri-jahroodi](https://github.com/mehdi-nasiri-jahroodi)

---
_Source: https://npm.io/package/react-calendar-datetime-picker · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._