# Date Time Picker

> React date and time picker in one popover: a calendar and a scrollable time list, 5 to 30 minute steps, past times disabled and a 12 or 24 hour clock.

- Kind: Component (Forms)
- Docs: https://ui.minidev.pro/docs/date-time-picker
- Source (registry JSON with the full file): https://ui.minidev.pro/r/date-time-picker.json
- License: MIT. One file, yours to edit after install.

## When to use

Use it for meetings, scheduled sends, deploy windows and deadlines, anywhere a single moment matters. The value is a `Date` (or `null` when empty). Pass `min={new Date()}` to block past days and the past slots of today; slots are `minuteStep` minutes apart. The trigger shows the value through `Intl.DateTimeFormat` (medium date, short time), and the time list follows the locale's 12 or 24 hour clock unless `hour12` is set. Pass `name` to submit it with a form as an ISO string. For a date alone use Calendar or DatePicker; for a time alone use TimePicker.

## Installation

### shadcn CLI (copies the source into your project)

```bash
npx shadcn@latest add @minidev/date-time-picker
```

Writes `components/ui/date-time-picker.tsx` plus the MiniDev files it is built from (button, calendar, popover) and installs its npm dependencies. Older CLI versions: `npx shadcn@latest add https://ui.minidev.pro/r/date-time-picker.json`.

### npm package

```bash
npm i minidev-ui-kit lucide-react
```

Add the tokens to your global stylesheet once:

```css
@import "tailwindcss";
@import "minidev-ui-kit/styles.css";
@source "../node_modules/minidev-ui-kit";
```

Next.js also needs `transpilePackages: ["minidev-ui-kit"]` in next.config.

## Import

After the shadcn install:

```tsx
import { DateTimePicker } from "@/components/ui/date-time-picker"
```

From the npm package:

```tsx
import { DateTimePicker } from "minidev-ui-kit/ui/date-time-picker"
```

## Usage

```tsx
import { DateTimePicker } from "@/components/ui/date-time-picker"

export function Example() {
  return (
    <DateTimePicker />
  )
}
```

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `Date \| null` | - | no | Controlled value, or `null` for empty. |
| `defaultValue` | `Date \| null` | `null` | no | Starting value when uncontrolled. |
| `onValueChange` | `(value: Date \| null) => void` | - | no | Fires with the new Date, or `null` after Clear. |
| `minuteStep` | `5 \| 15 \| 30` | `15` | no | Minutes between time slots. |
| `hour12` | `boolean` | - | no | Force a 12 or 24 hour clock. Defaults to the locale's clock. |
| `min` | `Date` | - | no | Earliest moment. Days before it and earlier slots on its day are disabled. |
| `max` | `Date` | - | no | Latest moment. Days after it and later slots on its day are disabled. |
| `disabled` | `boolean` | `false` | no | Disable the trigger. |
| `placeholder` | `string` | `"Pick a date and time"` | no | Trigger text while empty. |
| `timeZoneLabel` | `string` | - | no | Time zone note in the popover footer, such as "Times in Europe/Berlin". |
| `locale` | `string` | `"en-US"` | no | BCP 47 locale for the trigger, the calendar and the time labels. |
| `weekStartsOn` | `0 \| 1` | `0` | no | First column of the calendar week: 0 is Sunday, 1 is Monday. |
| `name` | `string` | - | no | Form field name. Submits the value as an ISO 8601 string in UTC, or "" when empty. |
| `id` | `string` | - | no | Id for a `<label htmlFor>` or FormField. |
| `className` | `string` | - | no |  |
| `aria-label` | `string` | - | no | What the moment is for, such as "Send at". The value is appended to it. |

## Examples

### Schedule a send

With min set to now, earlier days and the past slots of today cannot be picked.

```tsx
function ScheduleSend() {
  const [when, setWhen] = React.useState<Date | null>(null)
  const [now] = React.useState(() => new Date())
  return (
    <div className="flex flex-col gap-2">
      <label htmlFor="send-at" className="text-sm font-medium">Send invoice reminder</label>
      <DateTimePicker id="send-at" value={when} onValueChange={setWhen} min={now} aria-label="Send at" />
    </div>
  )
}
```

### 24 hour clock in a form

Half-hour slots, a 24 hour clock and a note naming the browser time zone, which is the zone the picker uses. With name set, FormData gets an ISO string in UTC.

```tsx
<form onSubmit={(e) => { e.preventDefault(); console.log(new FormData(e.currentTarget).get("deployAt")) }}>
  <DateTimePicker
    name="deployAt"
    defaultValue={new Date(2026, 10, 18, 22, 0)}
    minuteStep={30}
    hour12={false}
    weekStartsOn={1}
    timeZoneLabel={`Times in ${Intl.DateTimeFormat().resolvedOptions().timeZone}`}
    aria-label="Deploy at"
  />
  <Button type="submit" size="sm">Schedule deploy</Button>
</form>
```

## Keyboard interactions

| Key | Action |
| --- | --- |
| `Enter` or `Space` | On the trigger, opens the popover and focuses the selected day, or today. |
| `ArrowLeft` or `ArrowRight` or `ArrowUp` or `ArrowDown` | In the calendar, moves by day or week. PageUp and PageDown move by month, as in [`Calendar`](https://ui.minidev.pro/docs/calendar). |
| `Enter` or `Space` | In the calendar, picks the focused day and keeps the popover open. |
| `Tab` | Moves from the calendar to the time list, then to Clear and Now. |
| `ArrowDown` or `ArrowUp` | In the time list, moves to the next or previous free slot, skipping disabled ones. |
| `Home` or `End` | In the time list, moves to the first or last free slot. |
| `0-9` | In the time list, jumps to the first free slot that starts with the typed digits: 9 then 3 finds 9:30. Keys typed within 600ms add up. |
| `Enter` or `Space` | In the time list, picks the highlighted slot, closes the popover and returns focus to the trigger. |
| `Escape` | Closes the popover and returns focus to the trigger. |

## Accessibility

- The trigger is a Base UI `Popover.Trigger` with `aria-haspopup="dialog"` and `aria-expanded`. With `aria-label="Send at"`, its name becomes "Send at" plus the formatted value, or the placeholder when empty.
- The time list is a `role="listbox"` labelled by the visible "Time" heading. It is one tab stop and points at the highlighted slot with `aria-activedescendant`. Slots are `role="option"` with `aria-selected`; past or out-of-range slots have `aria-disabled`.
- On open, focus moves to the calendar's selected day or today, and the selected slot is scrolled to the middle of the list. On close, Base UI returns focus to the trigger.
- The trigger text and the hidden input are only filled in the browser: the server's time zone may differ from the visitor's, so rendering the time on the server could show the wrong hour.

## FAQ

### How do I disable past dates and times?

Pass `min={new Date()}`. Days before today are disabled in the calendar, and so are today's slots before that moment: with 15 minute steps at 14:07, the first free slot is 14:15. `max` works the same way at the other end, for example a deploy window that closes on Friday.

### Which time zone does DateTimePicker use?

The browser's. The value is a plain `Date`, the calendar, slots and trigger all show local time, and `timeZoneLabel` only prints a note in the footer. With `name`, the form submits `toISOString()`, which is UTC, so the server gets an unambiguous moment.

### How do I use it with React Hook Form or FormData?

For a plain `<form>`, pass `name` and a hidden input submits the ISO string, or `""` when empty. With React Hook Form, use a `Controller` and pass `value={field.value}` and `onValueChange={field.onChange}`. Clear sends `null`, so type the field `Date | null`.

### What happens if I pick a day before a time?

The first day you pick gets 09:00, or keeps the time already chosen; if that time is outside `min` or `max` on the new day, it moves to the first free slot. Picking a day keeps the popover open, while picking a time or pressing Now closes it. Now picks the first slot at or after the moment the popover opened.

## Rules for generating code

- Use semantic tokens only (bg, surface, sunken, border, fg, fg-muted, fg-subtle, ink, accent, success, warning, danger). Never raw hex or palette steps like blue-500.
- Shadows only from the set: shadow-xs, shadow-sm, shadow-raised, shadow-md, shadow-lg, shadow-overlay.
- Numbers use tabular-nums. Dark mode is the `dark` class on <html>; components never branch on theme.

## Dependencies

- npm: `lucide-react`
- Built from: [button](https://ui.minidev.pro/docs/button/md), [calendar](https://ui.minidev.pro/docs/calendar/md), [popover](https://ui.minidev.pro/docs/popover/md)

## Related

- [Calendar](https://ui.minidev.pro/docs/calendar/md): React calendar for Tailwind and shadcn: single, range or multiple dates, two months, preset ranges, a hover preview of the range and full arrow-key support.
- [Date Picker](https://ui.minidev.pro/docs/date-picker/md): Date picker built on the native date input, styled to match the rest of your form fields. Returns ISO date strings and supports disabled and labelled states.
- [Time Picker](https://ui.minidev.pro/docs/time-picker/md): React time picker built on the native time input, styled to match the other inputs, with a controlled value, onChange, disabled state and an aria-label.
- [Autocomplete](https://ui.minidev.pro/docs/autocomplete/md): Text input that filters string options as you type, using ARIA combobox and listbox roles. Works controlled or uncontrolled and lists up to eight matches.
- [Calendar Month](https://ui.minidev.pro/docs/calendar-month/md): Month calendar grid with weekday headers and clickable day cells that highlight the selected date. A simple Tailwind base for date views and schedulers.
- [Character Count](https://ui.minidev.pro/docs/character-count/md): Live React character counter that shows the current count against a limit and turns red when it goes over. Announces changes politely to screen readers.

---

All 557 components: https://ui.minidev.pro/llms.txt (full text: https://ui.minidev.pro/llms-full.txt).
