@moamfar/react-time-date-picker
Version:
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.
178 lines (134 loc) • 11.4 kB
Markdown
# 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.
[](#)
[](#)
[](#)
[](#)
[](#)
---
## 🧐 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)**
**Time Picker**
**Jalaali Date Picker**
**Hijri Date Picker**
---
## 🔴 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