useDatePicker
Hook that manages date picker state, calendar navigation, view switching, and popup positioning.
Usage#
import { useDatePicker } from '@primereact/headless/datepicker';
import { usePortal } from '@primereact/headless/portal';
import { usePositioner } from '@primereact/headless/positioner';const datepicker = useDatePicker({ ...options });
const {
rootProps,
inputProps,
triggerProps,
popupProps,
positionerProps,
bodyProps,
panelProps,
calendarProps,
headerProps,
titleProps,
prevProps,
nextProps,
selectMonthProps,
selectYearProps,
getTableProps,
tableHeaderProps,
tableHeaderRowProps,
weekDayCellProps,
tableBodyProps,
tableBodyRowProps,
getTableBodyCellProps,
getDayProps,
getMonthProps,
getYearProps,
state,
months,
weekDays,
monthPickerValues,
yearPickerValues,
getMonthName,
getYear
} = datepicker;
const portal = usePortal();
usePositioner({
anchor: state.anchorElement,
content: state.positionerElement,
side: 'bottom',
flip: true,
shift: true
});useDatePicker composes usePopover internally, managing calendar state, date selection, view switching, and keyboard navigation. See Primitive for a component-based API.
Features#
- Multiple views — day, month, and year pickers share one state;
switchToMonthView()/switchToYearView()change views programmatically - Selection modes — single, multiple, and range selection driven by
selectionMode - Calendar data —
months,weekDays,monthPickerValues, andyearPickerValuesprovide the grid data you render however you like - Per-cell props —
getDayProps,getMonthProps,getYearProps, andgetTableBodyCellPropscarry selection/focus/ARIA state per cell - Time picker —
showTimeandtimeOnlyadd time controls with formatted hour/minute/second/AM-PM helpers - Popup lifecycle — open/close, positioning, focus trap, and Escape handling via the internal popover
- Helpers —
parseValue(),isSelected(),isDateEquals(), andisInHoverRange()for custom rendering logic
Working with callbacks#
Controlled selection#
Pass value and onValueChange to drive the selected date(s) from outside state.
const [date, setDate] = React.useState(null);
const datepicker = useDatePicker({
value: date,
onValueChange: (e) => setDate(e.value)
});
<div {...rootProps}>
<input {...inputProps} />
<button {...triggerProps}></button>
{portal.state.mounted &&
state.opened &&
createPortal(
<div {...positionerProps}>
<div {...popupProps}>
<div {...bodyProps}>
<div {...panelProps}>
<div {...calendarProps}>
{/* Header: prev / title / next */}
<div {...headerProps}>
<button {...prevProps}></button>
<div {...titleProps}>
<button {...selectMonthProps}>{getMonthName()}</button>
<button {...selectYearProps}>{getYear()}</button>
</div>
<button {...nextProps}></button>
</div>
{/* Date view */}
{months.map((month, groupIndex) => (
<table {...getTableProps()}>
<thead {...tableHeaderProps}>
<tr {...tableHeaderRowProps}>
{weekDays.map((day, i) => (
<th key={i} {...weekDayCellProps}></th>Range and multiple selection#
Set selectionMode to switch modes — the value becomes an array of dates.
const datepicker = useDatePicker({
selectionMode: 'range',
onValueChange: (e) => {
const [start, end] = e.value ?? [];
console.log(start, end);
}
});Constraining the selectable range#
Use minDate / maxDate together with disabledDates or disabledDays to block specific days or recurring weekdays.
const datepicker = useDatePicker({
minDate: new Date(2024, 0, 1),
maxDate: new Date(2024, 11, 31),
disabledDays: [0, 6]
});Time and date-time pickers#
Enable showTime to pair the calendar with time controls, or timeOnly for pure time selection. dateFormat controls how the input renders the value.
const datepicker = useDatePicker({
showTime: true,
hourFormat: '12',
dateFormat: 'dd/mm/yy'
});Controlled popup visibility#
Use open and onOpenChange to coordinate the calendar popup with external state.
const [open, setOpen] = React.useState(false);
const datepicker = useDatePicker({
open,
onOpenChange: (e) => setOpen(e.value)
});Styling with data attributes#
Every prop object includes data-scope="datepicker" and a data-part that identifies the element. State-driven attributes appear or disappear automatically.
| Part | State Attributes |
|---|---|
root | data-disabled, data-invalid, data-readonly |
day | data-selected, data-disabled, data-today, data-other-month |
month | data-selected, data-disabled |
year | data-selected, data-disabled |
popup | data-open |
[data-scope='datepicker'][data-part='day'][data-selected='true'] {
background: var(--p-primary-color);
color: var(--p-primary-contrast-color);
}
[data-scope='datepicker'][data-part='day'][data-today='true'] {
font-weight: 600;
color: var(--p-primary-color);
}
[data-scope='datepicker'][data-part='day'][data-disabled='true'] {
opacity: 0.4;
pointer-events: none;
}API#
useDatePicker#
| Name | Type | Default |
|---|---|---|
value | string | string[] | Date | Date[] | — |
| Value of the component. | ||
defaultValue | string | string[] | Date | Date[] | — |
| The default value for the input when not controlled by `modelValue` . | ||
open | boolean | — |
| Controlled open state of the input tags overlay. | ||
defaultOpen | boolean | — |
| Default open state for uncontrolled mode. | ||
name | string | — |
| The name attribute for the element, typically used in form submissions. | ||
selectionMode | "multiple" | "range" | "single" | single |
| Defines the quantity of the selection. | ||
dateFormat | string | — |
| Format of the date. Defaults to PrimeVue Locale configuration. | ||
updateModelType | "string" | "date" | date |
| Type of the value to write back to modelValue. | ||
selectOtherMonths | boolean | false |
| Whether days in other months shown before or after the current month are selectable. This only applies if the showOtherMonths option is set to true. | ||
showIcon | boolean | false |
| When enabled, displays a button with icon next to input. | ||
icon | string | — |
| Icon of the datepicker button. | ||
prevIcon | string | — |
| Icon to show in the previous button. | ||
nextIcon | string | — |
| Icon to show in the next button. | ||
incrementIcon | string | — |
| Icon to show in each of the increment buttons. | ||
decrementIcon | string | — |
| Icon to show in each of the decrement buttons. | ||
numberOfMonths | number | 1 |
| Number of months to display. | ||
breakpoint | string | 769px |
| The breakpoint to define the maximum width boundary for datepicker panel. | ||
view | "date" | "month" | "year" | date |
| Type of view to display. | ||
minDate | Date | — |
| The minimum selectable date. | ||
maxDate | Date | — |
| The maximum selectable date. | ||
disabledDates | Date[] | — |
| Array with dates to disable. | ||
disabledDays | number[] | — |
| Array with disabled weekday numbers. | ||
maxDateCount | number | — |
| Maximum number of selectable dates in multiple mode. | ||
showOnFocus | boolean | true |
| When disabled, datepicker will not be visible with input focus. | ||
autoZIndex | boolean | true |
| Whether to automatically manage layering. | ||
baseZIndex | number | 0 |
| Base zIndex value to use in layering. | ||
showButtonBar | boolean | false |
| Whether to display today and clear buttons at the footer. | ||
shortYearCutoff | string | +10 |
| The cutoff year for determining the century for a date. | ||
showTime | boolean | false |
| Whether to display timepicker. | ||
timeOnly | boolean | false |
| Whether to display timepicker only. | ||
hourFormat | "12" | "24" | 24 |
| Specifies hour format. | ||
stepHour | number | 1 |
| Hours to change per step. | ||
stepMinute | number | 1 |
| Minutes to change per step. | ||
stepSecond | number | 1 |
| Seconds to change per step. | ||
showSeconds | boolean | false |
| Whether to show the seconds in time picker. | ||
showWeek | boolean | false |
| Whether to display week numbers. | ||
hideOnDateTimeSelect | boolean | false |
| Whether to hide the overlay on date selection when showTime is enabled. | ||
hideOnRangeSelection | boolean | false |
| Whether to hide the overlay on date selection is completed when selectionMode is range. | ||
timeSeparator | string | : |
| Separator of time selector. | ||
manualInput | boolean | true |
| Whether to allow entering the date manually via typing. | ||
size | "small" | "large" | — |
| Defines the size of the component. | ||
invalid | boolean | false |
| When present, it specifies that the component should have invalid state style. | ||
disabled | boolean | false |
| When present, it specifies that the component should be disabled. | ||
variant | "outlined" | "filled" | — |
| Specifies the input variant of the component. | ||
readOnly | boolean | false |
| When present, it specifies that an input field is read-only. | ||
placeholder | string | — |
| Placeholder text for the input. | ||
required | boolean | — |
| When present, it specifies that the component is a required field. | ||
appendTo | "body" | HTMLElement | "self" | body |
| A valid query selector or an HTMLElement to specify where the overlay gets attached. | ||
fluid | boolean | — |
| Spans 100% width of the container when enabled. | ||
ariaLabelledby | string | — |
| Establishes relationships between the component and label(s) where its value should be one or more element IDs. | ||
ariaLabel | string | — |
| Establishes a string value that labels the component. | ||
onValueChange | (event: useDatePickerValueChangeEvent) => void | — |
| Callback to invoke when the value changes. | ||
onDateSelect | (event: useDatePickerDateSelectEvent) => void | — |
| Callback to invoke when a date is selected. | ||
onMonthChange | (event: useDatePickerMonthChangeEvent) => void | — |
| Callback to invoke when the month changes. | ||
onYearChange | (event: useDatePickerYearChangeEvent) => void | — |
| Callback to invoke when the year changes. | ||
onTodayButtonClick | (event: useDatePickerTodayButtonClickEvent) => void | — |
| Callback to invoke when the today button is clicked. | ||
onClearButtonClick | (event: MouseEvent<HTMLButtonElement>) => void | — |
| Callback to invoke when the clear button is clicked. | ||
onInput | (event: ChangeEvent<HTMLInputElement>) => void | — |
| Callback to invoke on input event. | ||
onKeyDown | (event: KeyboardEvent<HTMLButtonElement | HTMLInputElement>) => void | — |
| Callback to invoke on keydown event. | ||
onFocus | (event: FocusEvent<HTMLInputElement>) => void | — |
| Callback to invoke on focus event. | ||
onBlur | (event: useDatePickerBlurEvent) => void | — |
| Callback to invoke on blur event. | ||
onOpenChange | (event: useDatePickerOpenChangeEvent) => void | — |
| Callback to invoke when the open state changes. | ||
closeOnEscape | boolean | true |
| Specifies if pressing escape key should hide the overlay. | ||
autoFocus | boolean | false |
| Whether to focus the first focusable element when the overlay is opened. | ||
trapped | boolean | false |
| When enabled, focus is trapped within the overlay (modal behavior). | ||
Accessibility#
Arrow keys navigate days, PageUp/PageDown switch months, Shift+PageUp/Down switch years, and Enter selects the focused date. See Primitive for full WAI-ARIA compliance details.