# 🗓️ React DatePicker Lite

A lightweight, accessible, and highly customizable React date picker component with TypeScript support. Built for modern React applications with performance and user experience in mind.

✨ Features

• 🪶 Ultra Lightweight - Less than 45KB minified + gzipped
• ♿ Fully Accessible - WCAG 2.1 compliant with keyboard navigation
• 📱 Mobile Friendly - Touch-optimized with responsive design
• 🎨 Highly Customizable - CSS variables and custom themes
• 🔧 TypeScript First - Built with TypeScript for better DX
• 🌍 Internationalization - Multi-language support
• 📅 Flexible Date Handling - Works with native Date objects or Moment.js
• ⚡ Zero Dependencies - No external runtime dependencies
• 🎯 Modern React - Hooks-based architecture
• 🧪 Well Tested - Comprehensive test coverage

🚀 Quick Start

Installation

npm install react-datepicker-lite

yarn add react-datepicker-lite

pnpm add react-datepicker-lite

Module Compatibility

React DatePicker Lite supports both ES Modules (ESM) and CommonJS environments:

• ✅ Modern bundlers (Vite, Webpack 5, Rollup) - Uses ESM version automatically
• ✅ Node.js CommonJS - Uses UMD version automatically
• ✅ Legacy bundlers - Falls back to UMD version
• ✅ TypeScript projects - Full type definitions included
• ✅ Browser environments - Works with both module types

The package automatically selects the appropriate format based on your environment thanks to the exports field in package.json.

Basic Usage

import React, { useState } from 'react';
import { DatePicker } from 'react-datepicker-lite';
import 'react-datepicker-lite/dist/index.css';

function App() {
  const [selectedDate, setSelectedDate] = useState<Date | null>(null);

  return (
    <DatePicker
      value={selectedDate}
      onChange={setSelectedDate}
      placeholder="Select a date"
    />
  );
}

📖 Documentation

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | Date \| null | null | The selected date | | onChange | (date: Date \| null) => void | - | Callback when date changes | | placeholder | string | "Select date" | Input placeholder text | | disabled | boolean | false | Disable the date picker | | minDate | Date | - | Minimum selectable date | | maxDate | Date | - | Maximum selectable date | | format | string | "MM/dd/yyyy" | Date display format | | locale | string | "en" | Locale for internationalization | | className | string | - | Custom CSS class | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Color theme |

Advanced Usage

Custom Styling

<DatePicker
  value={selectedDate}
  onChange={setSelectedDate}
  className="my-custom-datepicker"
  theme="dark"
/>

Date Range Restrictions

<DatePicker
  value={selectedDate}
  onChange={setSelectedDate}
  minDate={new Date()}
  maxDate={new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)} // 30 days from now
/>

Custom Date Format

<DatePicker
  value={selectedDate}
  onChange={setSelectedDate}
  format="dd/MM/yyyy"
  locale="en-GB"
/>

🎨 Theming

React DatePicker Lite supports extensive customization through CSS variables:

:root {
  --rdp-primary-color: #007bff;
  --rdp-secondary-color: #6c757d;
  --rdp-background-color: #ffffff;
  --rdp-border-color: #dee2e6;
  --rdp-border-radius: 4px;
  --rdp-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto;
  --rdp-font-size: 14px;
  --rdp-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
}

Dark Theme

[data-theme="dark"] {
  --rdp-primary-color: #0d6efd;
  --rdp-background-color: #212529;
  --rdp-border-color: #495057;
  --rdp-text-color: #ffffff;
}

🌍 Internationalization

The component supports multiple locales:

import { DatePicker } from 'react-datepicker-lite';

// French locale
<DatePicker
  value={selectedDate}
  onChange={setSelectedDate}
  locale="fr"
  format="dd/MM/yyyy"
/>

// German locale
<DatePicker
  value={selectedDate}
  onChange={setSelectedDate}
  locale="de"
  format="dd.MM.yyyy"
/>

♿ Accessibility

React DatePicker Lite is built with accessibility in mind:

• Keyboard Navigation: Full keyboard support with arrow keys, Enter, Escape
• Screen Reader Support: Proper ARIA labels and announcements
• Focus Management: Logical focus flow and visible focus indicators
• High Contrast: Supports high contrast mode and custom themes
• WCAG 2.1 Compliant: Meets AA accessibility standards

Keyboard Shortcuts

| Key | Action | |-----|--------| | Space/Enter | Open/close calendar | | Arrow Keys | Navigate dates | | Page Up/Down | Navigate months | | Shift + Page Up/Down | Navigate years | | Home/End | Go to start/end of week | | Escape | Close calendar |

📱 Mobile Support

The component is optimized for mobile devices:

• Touch-friendly interface with larger touch targets
• Responsive design that adapts to screen size
• Native mobile date picker fallback option
• Swipe gestures for month navigation

🧪 Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

🛠️ Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Run linting
npm run lint

# Format code
npm run format

📦 Bundle Size

React DatePicker Lite is designed to be lightweight:

• Minified: ~25KB
• Minified + Gzipped: ~8KB
• Zero runtime dependencies

⚡ Performance Optimization

Tree Shaking

React DatePicker Lite supports tree shaking out of the box. Import only what you need:

// ✅ Tree-shakable imports
import { DatePicker } from 'react-datepicker-lite';
import { Calendar } from 'react-datepicker-lite';
import { DateInput } from 'react-datepicker-lite';

// ❌ Avoid importing everything
import * as RDL from 'react-datepicker-lite';

Code Splitting

For large applications, consider code splitting the DatePicker:

// Lazy load the DatePicker
import { lazy, Suspense } from 'react';

const DatePicker = lazy(() => 
  import('react-datepicker-lite').then(module => ({ 
    default: module.DatePicker 
  }))
);

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <DatePicker value={date} onChange={setDate} />
    </Suspense>
  );
}

CSS Optimization

Load CSS efficiently:

// ✅ Import CSS once in your main file
import 'react-datepicker-lite/dist/index.css';

// Or use CSS-in-JS for better tree shaking
import { DatePicker } from 'react-datepicker-lite';
// CSS will be automatically included with the component

Memory Management

For applications with many DatePicker instances:

// ✅ Memoize callback functions
const handleDateChange = useCallback((date: Date | null) => {
  setSelectedDate(date);
}, []);

// ✅ Memoize the component when props don't change frequently
const MemoizedDatePicker = memo(DatePicker);

✅ Installation Verification

To verify that the package is working correctly, create a simple test component:

import React, { useState } from 'react';
import { DatePicker } from 'react-datepicker-lite';
import 'react-datepicker-lite/dist/index.css';

function TestDatePicker() {
  const [date, setDate] = useState<Date | null>(null);

  return (
    <div style={{ padding: '20px' }}>
      <h3>DatePicker Test</h3>
      <DatePicker
        value={date}
        onChange={setDate}
        placeholder="Click to select a date"
      />
      {date && (
        <p>Selected: {date.toLocaleDateString()}</p>
      )}
    </div>
  );
}

export default TestDatePicker;

If the component renders and you can select dates, the installation is successful!

🔧 Troubleshooting

Common Issues and Solutions

1. "Module not found" or Import Errors

Problem: Cannot import the DatePicker component.

Solutions:

// ✅ Correct import
import { DatePicker } from 'react-datepicker-lite';

// ❌ Incorrect - don't use default import
import DatePicker from 'react-datepicker-lite';

// ✅ Import multiple components
import { DatePicker, Calendar, DateInput } from 'react-datepicker-lite';

2. Styles Not Applied

Problem: DatePicker appears unstyled or broken.

Solution: Make sure to import the CSS file:

// ✅ Required CSS import
import 'react-datepicker-lite/dist/index.css';

// Or in your main CSS file
@import 'react-datepicker-lite/dist/index.css';

3. TypeScript Errors

Problem: TypeScript compilation errors.

Solutions:

// ✅ Proper typing
const [date, setDate] = useState<Date | null>(null);

// ✅ Event handler typing
const handleDateChange = (newDate: Date | null) => {
  setDate(newDate);
};

// ✅ Component props typing
import { DatePickerProps } from 'react-datepicker-lite';

4. Calendar Not Opening

Problem: Clicking the input doesn't open the calendar.

Possible causes and solutions:

• CSS conflicts: Check if other CSS is overriding styles
• Event propagation: Ensure no parent elements are stopping events
• Disabled state: Check if disabled prop is set to true

// ✅ Debug by adding event handlers
<DatePicker
  value={date}
  onChange={setDate}
  onFocus={() => console.log('Input focused')}
  onBlur={() => console.log('Input blurred')}
/>

5. Date Format Issues

Problem: Dates display in wrong format.

Solution: Use the format prop with proper format strings:

// ✅ Common formats
<DatePicker format="MM/DD/YYYY" />  // US format
<DatePicker format="DD/MM/YYYY" />  // European format
<DatePicker format="YYYY-MM-DD" />  // ISO format

6. Build/Bundle Issues

Problem: Module doesn't work in production build.

Solutions:

• Ensure you're importing from the correct path
• Check if your bundler supports ES modules
• For older bundlers, try importing the UMD version:

// For older bundlers
import { DatePicker } from 'react-datepicker-lite/dist/index.umd.js';

7. React Version Compatibility

Problem: Compatibility issues with React version.

Requirements:

• React >= 16.8.0 (hooks support required)
• React-DOM >= 16.8.0

# Check your React version
npm list react react-dom

# Update if needed
npm install react@latest react-dom@latest

8. SSR (Server-Side Rendering) Issues

Problem: Component breaks during server-side rendering.

Solution: Use dynamic imports for SSR frameworks:

// Next.js example
import dynamic from 'next/dynamic';

const DatePicker = dynamic(
  () => import('react-datepicker-lite').then(mod => ({ default: mod.DatePicker })),
  { ssr: false }
);

Getting Help

If you're still experiencing issues:

1. Check the console: Look for error messages in browser dev tools
2. Verify imports: Ensure all imports are correct
3. Test isolation: Try the component in a minimal setup
4. Check versions: Ensure compatible React and Node.js versions
5. Create an issue: Report bugs on GitHub

Debug Mode

Enable debug logging by setting a global variable:

// Add this before importing the component
(window as any).__RDL_DEBUG__ = true;

import { DatePicker } from 'react-datepicker-lite';

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the React community's need for a lightweight date picker
• Built with modern React patterns and TypeScript best practices
• Accessibility guidelines from WCAG 2.1 and WAI-ARIA

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions