Dates@knitui/dates

DateInput

DateInput is the free-typing single-date field: an editable Input trigger that opens a Calendar in a popover. Typing a value in valueFormat (default 'MMMM D, YYYY') parses and selects it; an unparseable string is preserved while typing and (with fixOnBlur, the default) reverts on blur; picking a day fills the input and closes the dropdown. Supports label, description, placeholder, error, required, clearable, withTime, and per-slot styles.

WebiOSAndroid4 style slots74 own props7 examples

Stories Source Tests Open in Storybook

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

Playground

Loading playground…

Playground

<DateInput />

Examples

Default

Single date with a label and placeholder.

Loading example…

DefaultSource Storybook

Clearable

Clearable — a clear button appears in the trigger once a value is set.

Loading example…

ClearableSource Storybook

Custom Format

Custom display + parse format via valueFormat.

Loading example…

Custom FormatSource Storybook

With Time

withTime preserves the time portion when valueFormat includes it.

Loading example…

With TimeSource Storybook

With Bounds

Bounded input — values outside [minDate, maxDate] are not accepted.

Loading example…

With BoundsSource Storybook

With Validation

Required field with a description and an error message.

Loading example…

With ValidationSource Storybook

Slot Styles Sugar

Per-slot styles sugar — props spread onto the composed parts.

Loading example…

Slot Styles SugarSource Storybook

Props

Prop	Type	Default	Description
`allowDeselect`	`boolean \| undefined`	`clearable`	Allow clearing the value by emptying the input / clicking the selected day.
`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.
`dateParser`	`((value: string) => DateStringValue \| Date \| null) \| undefined`	—	Parse user input into a date string (or `Date`); falls back to the locale-aware default parser.
`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`	—	Initial displayed level in uncontrolled mode.
`defaultValue`	`DateValue \| undefined`	—	Uncontrolled default value.
`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`.
`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).
`fixOnBlur`	`boolean \| undefined`	`true`	Restore the last valid value on blur when input is invalid.
`form`	`string \| undefined`	—	Associated `<form>` id forwarded to the hidden input.
`fullWidth` system	`boolean \| undefined`	`false`	Stretch the calendar 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: DateStringValue \| null) => void) \| undefined`	—	Called when the 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`.
`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).
`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	`CalendarSize \| undefined`	`'sm'`	Trigger / control size.
`sortDates`	`boolean \| undefined`	`true`	Sort the selected dates before `onChange` — `multiple` only.
`styles` system	`SlotStyles<DateInputStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching composed part (`wrapper`/`input`/`dropdown`/`calendar`).
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element
`value`	`DateValue \| undefined`	—	Controlled value.
`valueFormat`	`string \| undefined`	`'MMMM D, YYYY'`	`dayjs` format used to display (and parse) the 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.
`withTime`	`boolean \| undefined`	`false`	Preserve the time part of the value (set when `valueFormat` includes 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.

Style slots

Every part of DateInput can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Targets
`calendar`	Props for the inline `Calendar` inside the dropdown.
`dropdown`	Props for the `Popover.Dropdown` that holds the calendar.
`input`	Props for the editable trigger `Input`.
`wrapper`	Props for the `Input.Wrapper` (label/description/error surface).

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<TamaguiElement> \| undefined`

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.