Date Picker

Date pickers wrap a field and calendar trigger into a single input pattern for choosing one date.

Basic Usage

Use a controlled value when the chosen date needs to stay in sync with surrounding form state.

States

Show required (with clear), invalid, and disabled states when the picker is used inside forms.

Constraints

Bound selectable days with disablePast / disableFuture, weekday rules, and min / max.

Range

mode="range" with months="2" for a two-month booking-style picker.

Multiple

mode="multiple" lets users toggle several individual dates. The panel stays open while selecting, the control shows a count summary, and the value is a comma-separated, sorted list of ISO dates.

Date and Time

Compose DatePicker with TimePicker side by side; combine the values in your app code.

API

Slots

Name	Description
label	—
instructions	—
hint	—
start	—
end	—
clear-icon	—
expand-icon	—
footer	—

Props

Name	Description
ariaLabel	Type string | null Default null
customError	Custom validation message; also settable via setCustomValidity(). Type string | null Default null
defaultValue	Type string
disabled	Disables the control and excludes it from constraint validation. Type boolean Default false
disabledDates	Type string
disabledDaysOfWeek	Type string
disableFuture	Type boolean Default false
disablePast	Type boolean Default false
firstDayOfWeek	Type 'auto' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' Default auto
instructions	Type string
invalid	Type boolean Default false
isInvalid	Alias for invalid.
label	Type string
locale	Type string
max	Type string
maxRange	Type number Default 0
min	Type string
minRange	Type number Default 0
mode	Type PkDatePickerMode Default single
months	Type 1 | 2 Default 1
name	Name submitted with form data. Type string | null Default null
open	Type boolean Default false
pageBy	Type 'months' | 'single' Default months
placeholder	Type string
placement	Type PkPopupPlacement Default bottom
readonly	Type boolean Default false
readOnly	Alias for readonly.
required	Marks the control as required for form submission. Type boolean Default false
sideOffset	Type number Default 4
size	Type PkDatePickerSize Default default
value	Type string | Date
weekdayFormat	Type 'narrow' | 'short' | 'long' | undefined
width	When full, the control stretches to the host width. Type 'full' | undefined
withClear	Type boolean Default false
withInstructions	Type boolean Default false
withLabel	Type boolean Default false
withOutsideDays	Type boolean Default true
withWeekNumbers	Type boolean Default false

Methods

Name	Description
checkValidity()	Runs constraint validation without showing the browser UI.
hide()	—
reportValidity()	Runs constraint validation and shows the browser UI when invalid.
resetValidity()	Clears custom errors and re-syncs validity state.
setCustomValidity(message: string)	Sets or clears a custom validation message.
show()	—

Events

Name	Description
@change	—
@input	—
@pk-change	—
@pk-clear	—

Custom States

Name	Description	CSS selector
disabled	The control is disabled.	:state(disabled)
invalid	The control currently fails constraint validation.	:state(invalid)
optional	The control is not required.	:state(optional)
required	The control is required.	:state(required)
user-invalid	Invalid after the user has interacted with the control.	:state(user-invalid)
user-valid	Valid after the user has interacted with the control.	:state(user-valid)
valid	The control currently passes constraint validation.	:state(valid)

Dependencies

This component registers the following elements when it loads.

Name	Description
pk-popup	—