Dates@knitui/dates

MonthPickerInput

MonthPickerInput is the input-trigger month picker: an InputBase trigger opening a MonthPicker dropdown. Supports default / range / multiple selection, label / description / placeholder, and clearable.

WebiOSAndroid55 own props6 examples

Stories Source Tests Open in Storybook

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

Playground

Loading playground…

Playground

<MonthPickerInput />

Examples

Default

Single month with a label.

Loading example…

DefaultSource Storybook

Range

Range of months in the trigger.

Loading example…

RangeSource Storybook

Clearable

Clearable single month.

Loading example…

ClearableSource Storybook

Custom Format

Custom display format via valueFormat.

Loading example…

Custom FormatSource Storybook

Modal Dropdown

Presenting the picker in a centered modal instead of a popover.

Loading example…

Modal DropdownSource Storybook

With Validation

Required field with a description and an error message.

Loading example…

With ValidationSource 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`	—	Initial displayed level in uncontrolled mode.
`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`.
`error`	`ReactNode`	—	Error message / state.
`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.
`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`).
`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`.
`monthsListFormat`	`string \| undefined`	`'MMM'`	dayjs format for the month labels.
`name`	`string \| undefined`	—	Form field name forwarded to the hidden input.
`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: MonthPickerLevel) => void) \| undefined`	—	Called when the displayed level changes.
`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.
`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.
`onPreviousYear`	`((date: DateStringValue) => void) \| undefined`	—	Called when the previous-year button is clicked.
`placeholder`	`string \| undefined`	—	Input placeholder shown when there is no value.
`popoverProps`	`Partial<Omit<PopoverProps, "children">> \| undefined`	—	Props passed to the `Popover`.
`presets`	`MonthPickerPreset<Type>[] \| undefined`	—	Predefined values to pick from.
`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`	—
`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.
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element
`type`	`DatePickerType \| Type \| undefined`	—	Picker type: `range`, `multiple` or `default`.
`value`	`DatePickerValue<Type, DateValue> \| undefined`	—	Value for controlled component.
`valueFormat`	`string \| undefined`	`'MMMM YYYY'`	`dayjs` format for the displayed 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`).
`withCellSpacing`	`boolean \| undefined`	`true`	Separate controls/rows with spacing.
`withTime`	`boolean \| undefined`	`false`	Serialize the hidden field value with time.
`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.