@atawi/react-date-picker

v2.0.7

Published

2 months ago

A beautiful, customizable date and time picker component for React with multiple themes and localization support

Downloads

React Date Picker

npm version license bundle size

A beautiful, customizable date and time picker component for React with comprehensive built-in styling, multiple themes and localization support.

Features

📅 Multiple selection modes:
- Single date selection
- Date range selection
- Week range selection
🕒 Time picker with 12/24-hour format support
🌍 Internationalization support with date-fns locales
🎨 Beautiful built-in styling that works out of the box
🎯 Fully customizable styling with CSS classes
📱 Responsive and mobile-friendly design
♿ Accessibility-friendly with full keyboard navigation
🔧 TypeScript support
📝 Date notes and annotations support
✨ Confirmation mode with OK button
🎯 Standalone time picker component
📦 Tree-shakeable, lightweight, and works without any dependencies on CSS frameworks

Installation

npm install @atawi/react-date-picker

Setup

Import the package stylesheet once in your app entry, then import components:

import { DateTimePicker } from "@atawi/react-date-picker";

import "@atawi/react-date-picker/style.css";

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

  return <DateTimePicker value={date} onChange={setDate} showTime />;
}

The library includes comprehensive built-in styles that provide:

Beautiful hover states and interactions
Modern blue selection colors
Dark mode support
Fully responsive design
Smooth animations and transitions
Professional appearance suitable for any application

Basic Usage

import { DateTimePicker } from "@atawi/react-date-picker";

import "@atawi/react-date-picker/style.css";

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

  return <DateTimePicker value={date} onChange={setDate} showTime />;
}

Locale Example (date-fns)

Use a locale from date-fns/locale and pass it through the locale prop:

import { useState } from "react";
import { DateTimePicker } from "@atawi/react-date-picker";
import { fr } from "date-fns/locale";
import "@atawi/react-date-picker/style.css";

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

  return (
    <DateTimePicker value={date} onChange={setDate} showTime locale={fr} />
  );
}

Examples

Single Date Selection

// Basic date picker
<DateTimePicker
  value={date}
  onChange={setDate}
  mode="single"
  showTime={false}
/>

// With time selection
<DateTimePicker
  value={date}
  onChange={setDate}
  mode="single"
  showTime
  use24Hour={false}
/>

Date Range Selection

const [dateRange, setDateRange] = useState<Date | [Date, Date]>([
  new Date(),
  addDays(new Date(), 5),
]);

<DateTimePicker
  value={dateRange}
  onChange={setDateRange}
  mode="range"
  showTime={false}
/>;

Week Range Selection

const [weekRange, setWeekRange] = useState<Date | [Date, Date]>([
  startOfWeek(new Date()),
  endOfWeek(new Date()),
]);

<DateTimePicker
  value={weekRange}
  onChange={setWeekRange}
  mode="week"
  showTime={false}
/>;

With Date Notes

const notes = [
  {
    date: new Date(),
    note: "Today's special event: Team meeting at 2 PM",
  },
  {
    startDate: addDays(new Date(), 3),
    endDate: addDays(new Date(), 5),
    note: "Annual conference in New York",
  },
];

<DateTimePicker value={date} onChange={setDate} mode="single" notes={notes} />;

Auto-close Behavior (`closeOnSelect`)

Control whether the popover auto-closes after a selection. Defaults to "auto", which provides the most natural behavior for each mode.

| Value | Behavior | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "auto" | Closes after date pick when showTime is off. When showTime is on, waits and closes after the user picks the minute. In range/week mode, closes once the range is complete. | | true | Closes immediately on date pick, even when showTime is on. | | false | Never auto-closes; user must click outside or use a footer action. |

Providing a footer always overrides auto-close (assumed explicit confirm flow).

// Close immediately after date pick, skip waiting for time
<DateTimePicker value={date} onChange={setDate} showTime closeOnSelect />

// Disable auto-close entirely
<DateTimePicker value={date} onChange={setDate} closeOnSelect={false} />

Clearable Value with Custom Placeholder

Pass clearable to render an inline × button on the trigger that resets the value. The optional placeholder prop replaces the default "Select date" text shown when no value is selected. The cleared value is delivered as null through onChange (and an optional onClear callback).

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

<DateTimePicker
  value={date}
  onChange={setDate}
  mode="single"
  clearable
  placeholder="Pick a date…"
  onClear={() => console.log("cleared")}
/>;

Dark Mode

<DateTimePicker
  value={date}
  onChange={setDate}
  mode="single"
  showTime
  darkMode={true}
/>

With Confirmation Button

const [selectedDate, setSelectedDate] = useState(new Date());
const [isOpen, setIsOpen] = useState(false);

<DateTimePicker
  value={selectedDate}
  onChange={setSelectedDate}
  mode="single"
  showTime
  isOpen={isOpen}
  onOpenChange={setIsOpen}
  footer={
    <div
      style={{
        marginTop: "1rem",
        paddingTop: "1rem",
        borderTop: "1px solid #e5e7eb",
        display: "flex",
        justifyContent: "flex-end",
      }}
    >
      <ConfirmButton
        onConfirm={() => {
          // Handle confirmation
          setIsOpen(false);
        }}
      />
    </div>
  }
/>;

Standalone Time Picker

import { TimePicker } from "@atawi/react-date-picker";

import "@atawi/react-date-picker/style.css";

const [time, setTime] = useState<Date | [Date, Date]>(new Date());

<TimePicker value={time} onChange={setTime} use24Hour={false} />;

Custom Styling

You can customize the appearance using CSS classes:

const customStyles = {
  containerClassName: "my-date-picker",
  triggerClassName: "my-trigger-button",
  calendarClassName: "my-calendar",
  dayClassName: "my-day-button",
  selectedDayClassName: "my-selected-day",
};

<DateTimePicker value={date} onChange={setDate} styles={customStyles} />;

Then style with CSS:

.my-date-picker {
  /* Custom container styles */
}

.my-trigger-button {
  background: #f0f0f0;
  border: 2px solid #ccc;
  border-radius: 8px;
}

.my-selected-day {
  background: #ff6b6b;
  color: white;
}

With Min/Max Date Constraints

import { addDays, subDays } from "date-fns";

<DateTimePicker
  value={date}
  onChange={setDate}
  mode="single"
  showTime={false}
  minDate={subDays(new Date(), 3)}
  maxDate={addDays(new Date(), 30)}
/>;

Props API

DateTimePicker Props

| Prop | Type | --------------- | value | onChange | mode | showTime | use24Hour | disabled | disabledDates | minDate | maxDate | locale | notes | darkMode | isOpen | onOpenChange | footer | styles | showTooltip | clearable | placeholder | onClear | closeOnSelect | Default | Description | | -------------------------------------- | --------------- | --------------------------------------- | | Date \| [Date, Date] | new Date() | Selected date or date range | | (date: Date \| [Date, Date]) => void | Required | Callback when date changes | | 'single' \| 'range' \| 'week' | 'single' | Selection mode | | boolean | true | Show time picker | | boolean | false | Use 24-hour format | | boolean | false | Disable the picker | | Date[] | [] | Array of disabled dates | | Date | undefined | Earliest selectable date (inclusive) | | Date | undefined | Latest selectable date (inclusive) | | Locale | undefined | date-fns locale object | | DateNoteType[] | [] | Array of date notes | | boolean | false | Enable dark mode styling | | boolean | undefined | Control open state | | (isOpen: boolean) => void | undefined | Callback when open state changes | | React.ReactNode | undefined | Custom footer content | | StyleProps | {} | Custom style classes | | boolean | false | Enable tooltips in calendar | | boolean | false | Show a × button on the trigger to clear | | string | 'Select date' | Trigger text when no value is selected | | () => void | undefined | Called when the user clicks clear | | boolean \| 'auto' | 'auto' | Popover auto-close behavior (see above) |

TimePicker Props

| Prop | Type | Default | Description | | ----------- | ---------------------- | -------- | -------------------------- | | value | Date | Required | Selected time | | onChange | (date: Date) => void | Required | Callback when time changes | | use24Hour | boolean | false | Use 24-hour format | | disabled | boolean | false | Disable the picker | | darkMode | boolean | false | Enable dark mode styling | | styles | StyleProps | {} | Custom style classes |

Style Props

| Prop | Type | Description | | ---------------------- | -------- | -------------------------------- | | containerClassName | string | Class for the main container | | triggerClassName | string | Class for the trigger button | | calendarClassName | string | Class for the calendar container | | dayClassName | string | Class for calendar day buttons | | selectedDayClassName | string | Class for selected day | | rangeClassName | string | Class for days in range | | timePickerClassName | string | Class for time picker section |

Styling

The library comes with beautiful built-in styles that work out of the box. You can customize the appearance by:

Using the styles prop to apply custom CSS classes
Using the darkMode prop for automatic dark mode styling
Overriding CSS classes in your own stylesheet
Using CSS custom properties for theme customization

Built-in Themes

The library includes several built-in visual themes:

Default modern theme with blue accents
Dark mode support (automatic via media queries or manual via darkMode prop)
Material Design inspired styling
Clean, minimal appearance
Professional business styling

Accessibility

The component is built with accessibility in mind:

Full keyboard navigation support
ARIA labels and roles
Focus management
Screen reader friendly
High contrast mode support