npm package: @moamfar/react-time-date-picker
Description: A React component library providing elegant and intuitive iOS-style pickers for Gregorian dates times and Jalaali (Persian) dates and Hijri dates offering a consistent user experience in your React applications.
Author: moamfar
Latest version: 1.2.4

# React Time & Date Picker

A React component library providing elegant and intuitive iOS-style pickers for **Gregorian**, **Jalaali (Persian)**, and **Hijri** dates, as well as **time picking**, offering a smooth and consistent user experience for React applications.

[![React](https://img.shields.io/badge/React-%2320232a.svg?logo=react&logoColor=%2361DAFB)](#)
[![TailwindCSS](https://img.shields.io/badge/Tailwind%20CSS-%2338B2AC.svg?logo=tailwind-css&logoColor=white)](#)
[![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=fff)](#)
[![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?logo=javascript&logoColor=000)](#)
[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=fff)](#)

---

## 🧐 Features

- Time Picker (12-hour or 24-hour format)
- Date Picker (Gregorian)
- Jalaali (Persian) Date Picker
- Hijri Date Picker
- Auto-submit on scroll or manual submit
- Fully customizable via TailwindCSS classes
- Lightweight and responsive

---

## 🛠 Installation

1. Install the package via npm:

```bash
npm install @moamfar/react-time-date-picker
```

2. Import the styles in your project:

```ts
import "@moamfar/react-time-date-picker/dist/style.css";
```

3. Import the components in your React code:

```ts
import { DatePicker, TimePicker, CustomPicker } from "@moamfar/react-time-date-picker";
```

---

## 📸 Screenshots

**Date Picker (Gregorian)**
![Date Picker](./screenshot/DatePicker.png)

**Time Picker**
![Time Picker](./screenshot/TimePicker.png)

**Jalaali Date Picker**
![Date Picker Jalaali](./screenshot/Jalaali.png)

**Hijri Date Picker**
![Date Picker Hijri](./screenshot/Hijri.png)

---

## 🔴 Props

### TimePicker Props

| Prop                   | Description                                   | Required | Default Value                                                                                                |
| ---------------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `selectedTime`         | Value of returned time object                 | Yes      | `undefined`                                                                                                  |
| `setSelectedTime`      | Function to set the returned time object      | Yes      | `undefined`                                                                                                  |
| `is24Hours`            | Whether to use 24-hour format                 | No       | `false`                                                                                                      |
| `utcOffset`            | UTC offset (number or string)                 | No       | `210`                                                                                                        |
| `submitCallback`       | Function called after clicking submit button  | No       | `undefined`                                                                                                  |
| `submitTitle`          | Title of the submit button                    | No       | `"Submit"`                                                                                                   |
| `buttonClassName`      | Tailwind classes for the button               | No       | `"w-full bg-black rounded-md flex items-center justify-center h-10"`                                         |
| `submitTitleClassName` | Tailwind classes for button text              | No       | `"text-white"`                                                                                               |
| `containerClassName`   | Tailwind classes for the container            | No       | `"flex px-[10%] md:px-[25%] flex-row items-center justify-center w-full h-[18rem] overflow-hidden relative"` |
| `autoSubmitDebounce`   | Debounce time in ms for auto-submit on scroll | No       | `300`                                                                                                        |

---

### DatePicker Props

| Prop                   | Description                                           | Required | Default Value                                                                                                |
| ---------------------- | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `selectedDate`         | Value of returned date object                         | Yes      | `undefined`                                                                                                  |
| `setSelectedDate`      | Function to set the returned date object              | Yes      | `undefined`                                                                                                  |
| `type`                 | Calendar type: `georgian`, `jalaali`, `hijri`         | No       | `georgian`                                                                                                   |
| `maxYear`              | Maximum selectable year                               | No       | Current year                                                                                                 |
| `minYear`              | Minimum selectable year                               | No       | 100 years back                                                                                               |
| `maxDate`              | Maximum date allowed (timestamp)                      | No       | `undefined`                                                                                                  |
| `minDate`              | Minimum date allowed (timestamp)                      | No       | `undefined`                                                                                                  |
| `maxDateError`         | Error string when date exceeds maxDate                | No       | `undefined`                                                                                                  |
| `minDateError`         | Error string when date is before minDate              | No       | `undefined`                                                                                                  |
| `submitCallback`       | Function called after clicking submit button          | No       | `undefined`                                                                                                  |
| `submitTitle`          | Title of the submit button                            | No       | `"Submit"`                                                                                                   |
| `buttonClassName`      | Tailwind classes for the button                       | No       | `"w-full bg-black rounded-md flex items-center justify-center h-10"`                                         |
| `submitTitleClassName` | Tailwind classes for button text                      | No       | `"text-white"`                                                                                               |
| `containerClassName`   | Tailwind classes for the container                    | No       | `"flex px-[10%] md:px-[25%] flex-row items-center justify-center w-full h-[18rem] overflow-hidden relative"` |
| `columnsOrder`         | Order of columns (`day`, `month`, `year`)             | No       | `["day","month","year"]`                                                                                     |
| `sonnerOptions`        | Options for toast notifications (min/max date errors) | No       | `undefined`                                                                                                  |
| `autoSubmitDebounce`   | Debounce time in ms for auto-submit on scroll         | No       | `300`                                                                                                        |

---

### CustomPicker Props

| Prop                   | Description                                   | Required | Default Value                                                                                                |
| ---------------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `value`                | Selected value                                | No       | `undefined`                                                                                                  |
| `setValue`             | Function to set selected value                | Yes      | `undefined`                                                                                                  |
| `slides`               | Array of slide objects `{id, title}`          | Yes      | `undefined`                                                                                                  |
| `loading`              | Show loading state on submit button           | No       | `false`                                                                                                      |
| `submitCallback`       | Function called after clicking submit button  | No       | `undefined`                                                                                                  |
| `submitTitle`          | Title of the submit button                    | No       | `"ثبت"`                                                                                                      |
| `buttonClassName`      | Tailwind classes for the button               | No       | `"w-full bg-black rounded-md flex items-center justify-center h-10"`                                         |
| `submitTitleClassName` | Tailwind classes for button text              | No       | `"text-white"`                                                                                               |
| `containerClassName`   | Tailwind classes for the container            | No       | `"flex px-[10%] md:px-[25%] flex-row items-center justify-center w-full h-[18rem] overflow-hidden relative"` |
| `useTransform`         | Use 3D transform effect on wheel              | No       | `true`                                                                                                       |
| `autoSubmitDebounce`   | Debounce time in ms for auto-submit on scroll | No       | `300`                                                                                                        |

---

## 💻 Built With

- React
- TailwindCSS
- Embla Carousel
- moment
- moment-jalaali
- moment-hijri
- Lodash
- sonner (toast notifications)

---

## 📖 Usage Examples

**TimePicker Example:**

```tsx
<TimePicker
  selectedTime={{ hour: "12", minute: "30", meridiem: "PM" }}
  setSelectedTime={(time) => console.log(time)}
  is24Hours={false}
/>
```

**DatePicker Example:**

```tsx
<DatePicker
  selectedDate={{ day: 5, month: 8, year: 2025 }}
  setSelectedDate={(date) => console.log(date)}
  type="jalaali"
/>
```

**CustomPicker Example:**

```tsx
<CustomPicker
  value={{ id: 2, title: "Option 2" }}
  setValue={(val) => console.log(val)}
  slides={[
    { id: 1, title: "Option 1" },
    { id: 2, title: "Option 2" },
    { id: 3, title: "Option 3" },
  ]}
/>
```

---

## 🔗 License

MIT License