Date picker
A day or a span of days, chosen from a Calendar
Deployment window
Value: 2026-10-30
Empty field
October 2026
MTWTFSS
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
No date selected — the field reports null.
Chosen day, clearable
October 2026
MTWTFSS
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
Value: 2026-10-17
Bounded, Sunday start
October 2026
SMTWTFS
27
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
Value: 2026-10-14
Disabled field
Value: 2026-10-30
Booking window
Value: 2026-01-20 → 2026-02-04
October 2026
MTWTFSS
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
November 2026
MTWTFSS
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
1
2
3
4
5
6
Value: none
Installation
npx shadcn@latest add @sudokw/components-date-pickerimport { DatePicker } from "@gpuixui/components";Usage
import {
DatePicker,
DatePickerCalendar,
DatePickerContent,
DatePickerTrigger,
} from "@gpuixui/components/date-picker";
import { useState } from "react";
export const DeploymentWindow = () => {
const [due, setDue] = useState<string | null>("2026-10-30");
return (
<DatePicker
clearable
max="2026-12-18"
min="2026-10-26"
onValueChange={setDue}
today="2026-10-22"
value={due}
>
<DatePickerTrigger label="Deployment date" />
<DatePickerContent>
<DatePickerCalendar />
</DatePickerContent>
</DatePicker>
);
};A span is mode="range": the value is { from, to }, and it closes on the second day.
<DatePicker
mode="range"
clearable
onValueChange={setWindow}
today="2026-10-22"
value={window}
>
<DatePickerTrigger label="Booking window" />
<DatePickerContent>
<DatePickerCalendar label="Booking calendar" />
</DatePickerContent>
</DatePicker>Composition
DatePicker
├── DatePickerTrigger
└── DatePickerContent
└── DatePickerCalendarAPI reference
DatePicker
| Prop | Type | Default | Consequence |
|---|---|---|---|
mode | "single" | "range" | "single" | selects the value shape value and onValueChange speak |
value | string | null · { from, to } | null | none | the controlled value; undefined makes the picker uncontrolled |
defaultValue | string | null · { from, to } | null | null | the opening value when uncontrolled |
onValueChange | (value | range | null) => void | none | the chosen day, the span, or null from Clear |
weekStartsOn | 0 | 1 | 1 | the grid's first column |
min | string | unbounded | the first selectable ISO day, inclusive |
max | string | unbounded | the last selectable ISO day, inclusive |
clearable | boolean | false | adds the Clear row while a value is set |
disabled | boolean | false | leaves the tab order and does not open the surface |
today | string | the runtime clock | the ISO day the grid marks as today |
numberOfMonths | 1 | 2 | 1, or 2 in range mode | months painted side by side |
showOutsideDays | boolean | true | paints the neighbouring months' days |
captionLayout | "label" | "dropdown" | "label" | a caption, or month and year jump controls |
fromYear / toYear | number | today ± 10 | the years a dropdown may reach |
children | ReactNode | none | the trigger and the content, directly inside |
DatePickerTrigger
| Prop | Type | Default | Consequence |
|---|---|---|---|
placeholder | string | "Pick a date" | the text painted while no value is set |
label | string | — | the trigger's accessible name (the caret is decorative) |
variant | "primary" | "secondary" | "ghost" | "danger" | "secondary" | the trigger's fill and label role |
size | "sm" | "md" | "lg" | "md" | the control height the trigger takes from the theme's density |
disabled | boolean | false | adds to the root's disabled rule; never removes it |
className | string | — | joined after the recipe, so it wins conflicts |
testId | string | "date-picker-trigger" | the trigger's test identity |
onActivate | (event) => void | — | the action's one handler: it opens the surface from a press or an activating key |
onClick | (event) => void | — | the deprecated alias; only runs when onActivate is absent |
DatePickerContent
| Prop | Type | Default | Consequence |
|---|---|---|---|
side | "top" | "right" | "bottom" | "left" | "bottom" | where the surface anchors relative to the trigger |
align | "start" | "center" | "end" | "start" | the surface's alignment on that side |
sideOffset | number | 6 | the gap between trigger and surface, in pixels |
className | string | — | joined after the recipe |
children | ReactNode | none | the calendar, directly inside |
DatePickerCalendar
| Prop | Type | Default | Consequence |
|---|---|---|---|
label | string | "Calendar" | the grid's accessible name |
Keyboard
- Arrow LeftArrow Right
- moves a day
- Arrow DownArrow Up
- moves a week
- HomeEnd
- the week's first or last day
- Page UpPage Down
- the previous or next month
- EnterSpace
- chooses the focused day
- Escape
- closes the calendar
- Tab
- closes the calendar and lets focus move on
read from date-picker.tsx, calendar.tsx, logic.ts, popover.tsx
Edit this page on GitHubapps/docs/content/docs/components/date-picker.mdx