Dates@knitui/dates

DateTimePicker

DateTimePicker is the input-trigger date + time picker. Pressing the trigger opens a popover (or modal) holding an InlineDateTimePicker — a DatePicker plus one or two TimePickers and a submit button. Picking a date + time fills the trigger; the submit button (or Enter in a time input) commits and closes. type="range" selects a [start, end] pair with independent times. Values round-trip as YYYY-MM-DD HH:mm:ss strings.

WebiOSAndroid82 own props9 examples

Stories Source Tests Open in Storybook

import { DateTimePicker } from "@knitui/dates";

Playground

Loading playground…

Playground

<DateTimePicker />

Examples

Default

Single date + time selection (type="default").

Loading example…

DefaultSource Storybook

With Seconds

Seconds input shown in the dropdown and reflected in the trigger format.

Loading example…

With SecondsSource Storybook

Default Time Value

A new selection picks up defaultTimeValue instead of midnight.

Loading example…

Default Time ValueSource Storybook

Range

Range selection (type="range") — a start and end date, each with its own time.

Loading example…

RangeSource Storybook

Clearable

Clearable field — a clear button appears in the right section once a value is set.

Loading example…

ClearableSource Storybook

Min Max

Bounded selection — out-of-[minDate, maxDate] days are disabled and the value is clamped on close.

Loading example…

Min MaxSource Storybook

Custom Format

Custom trigger format via a valueFormat string.

Loading example…

Custom FormatSource Storybook

Modal Dropdown

Opens in a centered modal instead of a popover (dropdownType="modal").

Loading example…

Modal DropdownSource Storybook

Disabled

Disabled trigger — the dropdown can't open.

Loading example…

DisabledSource Storybook

Props

Prop	Type	Default	Description
`allowDeselect`	`(Type extends "default" ? boolean : never) \| undefined`	—	Whether the user can deselect a date by clicking it again — `type="default"` only.
`allowSingleDateInRange`	`(Type extends "range" ? boolean : never) \| undefined`	—	Whether a single day can be selected as a range — `type="range"` only.
`ariaLabels`	`CalendarAriaLabels \| undefined`	—	`aria-label`s for the controls on the different levels.
`clearable`	`boolean \| undefined`	`false`	Show a clear button in the right section when the field has a value.
`clearButtonProps`	`CloseButtonProps \| undefined`	—	Props passed to the clear button.
`closeOnChange`	`boolean \| undefined`	`true`	Close the dropdown when the value changes (not applicable to `multiple`).
`columnsToScroll`	`number \| undefined`	`numberOfColumns`	Number of columns to scroll with the next/prev buttons.
`date`	`string \| Date \| undefined`	—	Displayed date in controlled mode.
`decadeLabelFormat`	`DecadeLabelFormat \| undefined`	`'YYYY'`	dayjs format for the decade label, or a function returning it.
`defaultDate`	`string \| Date \| undefined`	—	Initial displayed date in uncontrolled mode.
`defaultLevel`	`CalendarLevel \| undefined`	`'month'`	Initial displayed level in uncontrolled mode.
`defaultTimeValue`	`string \| undefined`	—	Default time value in `HH:mm` or `HH:mm:ss` format. Assigned to the time when a date is selected.
`defaultValue`	`DatePickerValue<Type, DateValue> \| undefined`	—	Default value for uncontrolled component.
`description`	`ReactNode`	—	Description rendered below the label.
`disabled` system	`boolean \| undefined`	—
`dropdownType`	`PickerInputDropdownType \| undefined`	`'popover'`	Whether the picker opens in a floating `Popover` or a centered `Modal`.
`enableKeyboardNavigation`	`boolean \| undefined`	`true`	Enable enhanced keyboard navigation (web only): Ctrl/Cmd+Arrow steps a year, Ctrl/Cmd+Shift+Arrow steps a decade, `Y` opens the year view.
`endTimePickerProps`	`Omit<TimePickerProps, "value" \| "defaultValue"> \| undefined`	—	Props passed down to the end time `TimePicker` component in range mode.
`error`	`ReactNode`	—	Error message / state.
`excludeDate`	`((date: DateStringValue) => boolean) \| undefined`	—	Predicate marking a day disabled.
`firstDayOfWeek`	`DayOfWeek \| undefined`	`DatesProvider` (1)	First weekday of each row, `0` (Sunday) … `6` (Saturday).
`form`	`string \| undefined`	—	Associated `<form>` id forwarded to the hidden input.
`fullWidth` system	`boolean \| undefined`	`false`	Stretch the list (and its controls) to the full width of its container.
`getDayAriaLabel`	`((date: DateStringValue) => string) \| undefined`	—	Assigns each `Day` an `aria-label` based on its date.
`getDayProps`	`((date: DateStringValue) => Partial<DayProps>) \| undefined`	—	Passes props down to every `Day` (wins over `styles.day`).
`getMonthControlProps`	`((date: DateStringValue) => Partial<PickerControlProps>) \| undefined`	—	Passes props down to each month `PickerControl`, keyed by date (wins over `styles.control`).
`getYearControlProps`	`((date: DateStringValue) => Partial<PickerControlProps>) \| undefined`	—	Passes props down to each year `PickerControl`, keyed by date (wins over `styles.control`).
`headerControlsOrder`	`CalendarHeaderControlName[] \| undefined`	`['previous', 'level', 'next']`	Order in which the controls are rendered.
`hideOutsideDates`	`boolean \| undefined`	`false`	Hide days outside the current month.
`hideWeekdays`	`boolean \| undefined`	`false`	Hide the weekday header row.
`highlightToday`	`boolean \| undefined`	`false`	Highlight today with a border.
`label`	`ReactNode`	—	Field label rendered above the trigger.
`labelSeparator`	`string \| undefined`	—	Separator rendered between the two dates of a range value.
`level`	`CalendarLevel \| undefined`	—	Current displayed level in controlled mode.
`locale`	`string \| undefined`	—	dayjs locale; falls back to the value defined in `DatesProvider`.
`maxDate`	`string \| Date \| undefined`	—	Maximum possible date in `YYYY-MM-DD` format or a `Date` object.
`maxLevel`	`CalendarLevel \| undefined`	`'decade'`	Max level the user can zoom out to.
`minDate`	`string \| Date \| undefined`	—	Minimum possible date in `YYYY-MM-DD` format or a `Date` object.
`modalProps`	`Partial<Omit<ModalProps, "children">> \| undefined`	—	Props passed to the `Modal` when `dropdownType="modal"` (ignored for the `popover` dropdown). Spread before the component's own `opened`/`onClose`/ `title`, so those always win; the `withCloseButton={false}` default is overridable via `modalProps.withCloseButton`.
`monthLabelFormat`	`DateLabelFormat \| undefined`	`'MMMM YYYY'`	dayjs format for the month label, or a function returning it.
`monthsListFormat`	`string \| undefined`	`'MMM'`	dayjs format for the month labels.
`name`	`string \| undefined`	—	Form field name forwarded to the hidden input.
`nextIcon`	`ReactNode`	—	Replace the next-button icon.
`nextLabel`	`string \| undefined`	—	Next-button `aria-label`.
`numberOfColumns`	`number \| undefined`	`1`	Number of columns displayed next to each other.
`onChange`	`((value: DatePickerValue<Type, string>) => void) \| undefined`	—	Called when value changes.
`onDateChange`	`((date: DateStringValue) => void) \| undefined`	—	Called when the displayed date changes.
`onDropdownClose`	`(() => void) \| undefined`	—	Called when the dropdown closes, after the incomplete-range reset. Lets a wrapper run extra close-time logic (e.g. `DateTimePicker`'s min/max clamp).
`onLevelChange`	`((level: CalendarLevel) => void) \| undefined`	—	Called when the displayed level changes.
`onMonthMouseEnter`	`((event: unknown, date: DateStringValue) => void) \| undefined`	—	Called when the pointer enters a month control (web hover; used for range preview). Cross-platform — the event type is opaque, never a DOM event.
`onMonthSelect`	`((date: DateStringValue) => void) \| undefined`	—	Called when the user selects a month.
`onMouseLeave`	`((event: unknown) => void) \| undefined`	—	Called when the pointer leaves the calendar root (web hover; used by range pickers to clear the hover preview). Cross-platform — the event type is opaque, never a DOM event; Tamagui no-ops it on native.
`onNextDecade`	`((date: DateStringValue) => void) \| undefined`	—	Called when the next-decade button is clicked.
`onNextMonth`	`((date: DateStringValue) => void) \| undefined`	—	Called when the next-month button is clicked.
`onNextYear`	`((date: DateStringValue) => void) \| undefined`	—	Called when the next-year button is clicked.
`onPreviousDecade`	`((date: DateStringValue) => void) \| undefined`	—	Called when the previous-decade button is clicked.
`onPreviousMonth`	`((date: DateStringValue) => void) \| undefined`	—	Called when the previous-month button is clicked.
`onPreviousYear`	`((date: DateStringValue) => void) \| undefined`	—	Called when the previous-year button is clicked.
`onYearMouseEnter`	`((event: unknown, date: DateStringValue) => void) \| undefined`	—	Called when the pointer enters a year control (web hover; used for range preview). Cross-platform — the event type is opaque, never a DOM event.
`onYearSelect`	`((date: DateStringValue) => void) \| undefined`	—	Called when the user selects a year.
`placeholder`	`string \| undefined`	—	Input placeholder shown when there is no value.
`popoverProps`	`Partial<Omit<PopoverProps, "children">> \| undefined`	—	Props passed to the `Popover`.
`presets`	`DatePickerPreset<Type>[] \| undefined`	—	Predefined values to pick from.
`previousIcon`	`ReactNode`	—	Replace the previous-button icon.
`previousLabel`	`string \| undefined`	—	Previous-button `aria-label`.
`readOnly`	`boolean \| undefined`	—	Prevent the value from being changed by the user (the dropdown stays closed).
`ref`	`Ref<TamaguiElement> \| undefined`	—
`renderDay`	`RenderDay \| undefined`	—	Custom renderer for each day's content.
`required`	`boolean \| undefined`	—	Mark the field as required (adds the asterisk to the label).
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined`	—
`size` system	`InlineDateTimePickerSize \| undefined`	`'sm'`	Trigger / control size.
`sortDates`	`boolean \| undefined`	`true`	Sort the selected dates before `onChange` — `multiple` only.
`submitButtonProps`	`ActionIconProps \| undefined`	—	Props passed down to the submit button.
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element
`timePickerProps`	`Omit<TimePickerProps, "value" \| "defaultValue"> \| undefined`	—	Props passed down to the `TimePicker` component.
`type`	`DatePickerType \| Type \| undefined`	—	Picker type: `range`, `multiple` or `default`.
`value`	`DatePickerValue<Type, DateValue> \| undefined`	—	Value for controlled component.
`valueFormat`	`string \| ((date: DateStringValue) => string) \| undefined`	`"DD/MM/YYYY HH:mm"`	`dayjs` format for the displayed value, or a function that receives the value as a `YYYY-MM-DD HH:mm:ss` string and returns the formatted value.
`valueFormatter`	`DateFormatter \| undefined`	—	Format the selected dates into the trigger string (defaults by picker type).
`variant` system	`InputVariant \| undefined`	`'default'`	Visual variant of the input chrome (`default`/`filled`/`unstyled`).
`weekdayFormat`	`DateLabelFormat \| undefined`	`'dd'`	dayjs format for weekday names, or a custom renderer.
`weekendDays`	`DayOfWeek[] \| undefined`	`DatesProvider` ([0, 6])	Indices of weekend days.
`withCellSpacing`	`boolean \| undefined`	`true`	Separate controls/rows with spacing.
`withSeconds`	`boolean \| undefined`	`false`	Whether the seconds input is displayed.
`withTime`	`boolean \| undefined`	`false`	Serialize the hidden field value with time.
`withWeekNumbers`	`boolean \| undefined`	`false`	Display a leading week-number column.
`yearLabelFormat`	`DateLabelFormat \| undefined`	`'YYYY'`	dayjs format for the year label, or a function returning it.
`yearsListFormat`	`string \| undefined`	`'YYYY'`	dayjs format for the year labels.

Plus 495 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.