Components/Form
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/datepicker
Date pickers allow users to select or enter a specific date. It's a combination of the <Input/>, <Calendar/> and <Popover/> components.
<TimeInput/> instead.Adjust the size using the size prop. It supports 3 sizes:
large when the date input needs emphasis.medium.small.Control the status using the status prop. There are 3 states:
error highlights invalid dates.warning highlights dates that can't be validated or might impact the user negatively.loading shows that the server is loading the selected value.Add text that explains the status or what action the user should take with the statusMessage prop.
Showing the status message inline, directly below the date picker is preferred in all default cases.
<FormField/> and add the statusMessage.statusMessage prop.View more inline status message examples in <FormField/>.
Control the input interaction with these props:
readOnly to display dates that cannot be overwritten (but can still be copied).disabled prop. Use it to highlight an unavailable selection.Use the clearButton prop to add a button that clears the selected date easily.
Set appropriate formatting per country with locale and dateStyle props.
dateStyle supports 2 values:
short.medium prop.long prop.Use firstDayOfWeek to adjust which day of the week is shown first in the calendar view. Overwrite the default value for Sunday (0) with a number representing any other day of the week (Monday = 1, Tuesday = 2, etc.).
Make it easier for users to select dates far in the past or future with the showMonthDropdown and showYearDropdown. These dropdowns will show inside the calendar view.
Control the date ranges that users can select with the following props:
excludePastDates.filterDate .The component's built-in validation feature covers these cases:
formatError - when a user types in a date that is invalid and impossible to parse.outOfBoundsError - when a user types in a date that is out of the accepted range. This validation is triggered when the excludePastDates or filterDate props are enabled.Get informed about a validation event by using the onValidate callback function. It provides these parameters: validationType, input value and format.
To apply custom validations to the component, use onChange, value and status together with the statusMessage prop.
Requires use of external package. In this example use-mask-input package is used.
Use the date picker to control the design of calendar components on the user's site.
Use the date picker together with <TimeInput/> for scheduling appointments, events and more.
To help users enter the correct date format, use helper text below the date picker which describes the expected date format.
This will help prevent user errors.
| Name | Type | Default | Description |
|---|---|---|---|
autoFocus | boolean | true | Focus selected day automatically when component mounts or updates. |
calendarDataHook | string | — | Applies a data-hook HTML attribute for date picker calendar view. |
calendarProps | { size?: "small" | "medium" | undefined; } | — | Defines the size of calendar opened. |
clearButton | boolean | — | Display a clear button (x) on a non-empty field. |
clearButtonAriaLabel | string | — | Aria label for the clear button. |
clearButtonTooltipContent | ReactNode | — | When provided, hovering displays a tooltip. |
clearButtonTooltipProps | TooltipCommonProps | — | Allows to pass common tooltip props to the tooltip of the clear button. |
containFocus | boolean | — | Specifies whether focus is trapped in the calendar while autoFocus is enabled, and returned to the previously focused element when the calendar unmounts. |
customInput | ReactNode | — | Override a field with a custom input element. If you only need to pass custom props to the <Input/>, then use inputProps instead. |
dataHook | string | — | Applies as data-hook HTML attribute that can be used in the tests. |
dateIndication | FC<dateIndicationProps> | — | ##### Add an indication under a specific date. Function returns the indication node of a specific date or null if this day doesn't have an indication. - param {date: Date, isSelected: boolean } - date - a date - isSelected - whether this date is the selected date - return {React.node} - the indication node of a specific date or null if this day doesn't have an indication. |
dateStyle | "medium" | "short" | "long" | 'short' | Sets date format of locale. |
disabled | boolean | false | Specify whether a field should be disabled or not. |
disableKeyboardType | boolean | false | Disable typing the in the input. When true, choosing a date is possible only by picking from the calendar. Default: false. |
excludePastDates | boolean | false | Specify whether past dates should be selectable or not. |
filterDate | (date: Date) => boolean | — | ##### Specify selectable dates: * param {Date} date - a date to check * return {boolean} - true if date should be selectable, false otherwise |
firstDayOfWeek | 0 | 1 | 5 | 2 | 3 | 4 | 6 | — | Specify the starting day of a week, allowing only from 0 to 6 (Sunday to Saturday). The default value is 1 which means Monday. |
initialOpen | boolean | — | Specify whether the calendar is initially visible or not. |
inputDataHook | string | — | Applies a data-hook HTML attribute for date picker input. |
inputProps | Partial<InputProps> | — | Allows you to pass default Input component properties. |
inputRef | null | (instance: HTMLInputElement | null) => void | RefObject<HTMLInputElement> | — | Ref to the underlying <input> DOM element. Accepts callback and object refs. Use for input masking libraries. Memoize callback refs to avoid reattaching. |
leftArrowAriaLabel | string | — | Defines a string value that labels the left arrow in calendar header. |
leftArrowAriaLabelledBy | string | — | Identifies the element that labels the left arrow in calendar header. |
locale | "th" | "tr" | "id" | "fr" | "no" | "en" | "en-US" | "en-GB" | "en-AU" | "en-CA" | "ar" | "bg" | "ca" | "zh" | "zh-TW" | "zh-HK" | "zh-MO" | "cs" | "da" | "nl" | "fi" | "fr-CA" | "fr-CH" | "fr-BE" | "de" | "de-CH" | "de-AT" | "el" | "he" | "hi" | "hu" | "it" | "ja" | "ko" | "lt" | "ms" | "nb" | "nn" | "pl" | "pt-BR" | "pt" | "ro" | "ru" | "sk" | "sl" | "es" | "es-419" | "es-AR" | "es-MX" | "es-US" | "sv" | "tl" | "uk" | "vi" | — | Specify date picker instance locale. |
monthDropdownAriaLabel | string | — | Defines a string value that labels the months dropdown in calendar header. |
monthDropdownAriaLabelledBy | string | — | Identifies the element that labels the months dropdown in calendar header. |
numOfMonths | 1 | 2 | 1 | Allows to display multiple months at once. Currently it shows 1 or 2 months only. |
onChange (required) | (date: Date) => void | — | Provides a callback function when day in selected in the calendar. |
onClear | (event: ChangeEvent<HTMLInputElement> | KeyboardEvent<HTMLButtonElement> | MouseEvent<HTMLButtonElement, MouseEvent>) => void | — | Defines a callback function which is called when the field is cleared, either with the clear button (X) or by deleting the typed value. The date picker doesn't call onChange for an empty value, so use this callback to reset value. |
onClose | () => void | — | Defines a callback function that is called whenever a user presses escape, clicks outside of the element or a date is selected and shouldCloseOnSelect is set. Receives an event as a first argument. |
onKeyDown | (event: KeyboardEvent<Element>) => void | — | Provides a callback function when any key is clicked in the calendar. |
onMonthChange | (monthStart: Date) => void | — | Defines a callback function that is called with the date of the first day of the month whenever the user selects a month in the calendar. |
onOpen | () => void | — | Defines a callback function which is called when date picker is opened. |
onValidate | ({ validationType, format, value, }: { format?: string | undefined; validationType: "outOfBoundsError" | "formatError" | "valid"; value: string; }) => void | — | Defines a callback function which is called on cases when date is validated. - {validationType: 'outOfBoundsError' | 'formatError' | 'valid', format: string, value: string } - validationType - type 'formatError' is set when validated date is in the wrong date format - type 'outOfBoundsError' is set when 'excludePastDates' is true and date input is before today - type 'valid' is set when entered date is valid - format - is set to valid date format - value - is set to current input value |
placeholderText | string | — | Defines a placeholder of the field. |
popoverProps | PopoverCommonProps | — | Allows you to pass popover properties. The default placement value depends on the rtl prop - would be 'top-start' when rtl=false and 'top-end' in case of rtl=true. |
readOnly | boolean | — | Specify whether date picker input is readOnly or not. |
renderFooter | () => ReactNode | — | Function which renders a provided node at the bottom of the Calendar. |
rightArrowAriaLabel | string | — | Defines a string value that labels the right arrow in calendar header. |
rightArrowAriaLabelledBy | string | — | Identifies the element that labels the right arrow in calendar header. |
rtl | boolean | false | Specify whether RTL mode is enabled or not. When true, the keyboard navigation is changed, meaning pressing the right arrow navigates to the previous day, and pressing the left arrow navigates to the next day. |
selectionMode | "day" | "range" | 'day' | Whether the user should be able to select a date range, or just a single day. |
shouldCloseOnSelect | boolean | true | Specify whether the calendar closes on day selection. |
showDrawerOnMobile | boolean | true | Specifies whether the calendar opens in a bottom <Drawer/> when WixDesignSystemProvider has mobile enabled. |
showMonthDropdown | boolean | false | Displays a selectable monthDropdown. |
showYearDropdown | boolean | false | Displays a selectable yearDropdown. |
size | "small" | "medium" | "large" | — | Specifies the size of the input. |
status | "error" | "warning" | "loading" | — | Controls the status of a field. |
statusMessage | ReactNode | — | Defines the status message to be displayed on status icon hover. If not given or empty, the tooltip won't be shown. |
today | Date | — | Sets today's date. The today indication is added automatically according to the user timezone but in some cases, we need the ability to add the today indication based on the business timezone. |
validate | boolean | — | Enables internal input validation. |
value | Date | — | Defines the selected date. |
width | string | number | '150px' | Sets the width of picker input in pixels or percentage. |
yearDropdownAriaLabel | string | — | Defines a string value that labels the years dropdown in calendar header. |
yearDropdownAriaLabelledBy | string | — | Identifies the element that labels the years dropdown in calendar header. |
zIndex | number | — | Set a desired z-index for date picker popover. |
No testkit for this component — it doesn't expose a unidriver testkit.
onChange, and neither does pressing Enter on an empty input. Clearing the input by typing now calls onClear, the same callback the clear button uses, so reset value there. onClear now receives the triggering mouse, keyboard or change event. (#17338)Last updated: 30 October 2026