DatePicker

Components/Form

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/datepicker

Overview

Copy

Date pickers allow users to select or enter a specific date. It's a combination of the <Input/>, <Calendar/> and <Popover/> components.

Do

  • Use it to select dates in the recent past or near future.
  • Make it easier to select dates far in the past or in the future with month and year selection in the calendar (e.g., when entering a birth date or expiration date).

Don't

  • Don't use it to select time. Use <TimeInput/> instead.

Feature examples

Size

Adjust the size using the size prop. It supports 3 sizes:

  • Use large when the date input needs emphasis.
  • For most common cases, use the default medium.
  • In more dense and compact layouts, use small.
Copy

Status

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.
Copy

Status message

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.

  • To add an accessible inline message, wrap the component in a <FormField/> and add the statusMessage.
  • To add a status message in a tooltip that requires users to hover on the icon, use the statusMessage prop.

View more inline status message examples in <FormField/>.

Copy

Read-only and disabled

Control the input interaction with these props:

  • Use readOnly to display dates that cannot be overwritten (but can still be copied).
  • Disable all input interactions with the disabled prop. Use it to highlight an unavailable selection.
Copy

Clear button

Use the clearButton prop to add a button that clears the selected date easily.

Copy

Locale and date style

Set appropriate formatting per country with locale and dateStyle props.

dateStyle supports 2 values:

  • In most cases, the default style should be short.
  • Give the month more emphasis with the medium prop.
  • Show day and month in more detail with the long prop.
Copy

First day of the week

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.).

Copy

Year and month selections

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.

Copy

Excluding dates

Control the date ranges that users can select with the following props:

  • Stop users from selecting dates in the past with excludePastDates.
  • Don't allow users to select a specific set or range of dates with filterDate .
Copy

Developer examples

Built-in date validation

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.

Copy

Custom date validations

To apply custom validations to the component, use onChange, value and status together with the statusMessage prop.

Copy

Masked DatePicker using use-mask-input

Requires use of external package. In this example use-mask-input package is used.

Copy

Common use case examples

Settings panel

Use the date picker to control the design of calendar components on the user's site.

Copy

Together with time input

Use the date picker together with <TimeInput/> for scheduling appointments, events and more.

Copy

Accessibility examples

Helper text

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.

Copy

Code

Copy

Props

NameTypeDefaultDescription
autoFocusbooleantrueFocus selected day automatically when component mounts or updates.
calendarDataHookstring—Applies a data-hook HTML attribute for date picker calendar view.
calendarProps{ size?: "small" | "medium" | undefined; }—Defines the size of calendar opened.
clearButtonboolean—Display a clear button (x) on a non-empty field.
clearButtonAriaLabelstring—Aria label for the clear button.
clearButtonTooltipContentReactNode—When provided, hovering displays a tooltip.
clearButtonTooltipPropsTooltipCommonProps—Allows to pass common tooltip props to the tooltip of the clear button.
containFocusboolean—Specifies whether focus is trapped in the calendar while autoFocus is enabled, and returned to the previously focused element when the calendar unmounts.
customInputReactNode—Override a field with a custom input element. If you only need to pass custom props to the <Input/>, then use inputProps instead.
dataHookstring—Applies as data-hook HTML attribute that can be used in the tests.
dateIndicationFC<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.
disabledbooleanfalseSpecify whether a field should be disabled or not.
disableKeyboardTypebooleanfalseDisable typing the in the input. When true, choosing a date is possible only by picking from the calendar. Default: false.
excludePastDatesbooleanfalseSpecify 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
firstDayOfWeek0 | 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.
initialOpenboolean—Specify whether the calendar is initially visible or not.
inputDataHookstring—Applies a data-hook HTML attribute for date picker input.
inputPropsPartial<InputProps>—Allows you to pass default Input component properties.
inputRefnull | (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.
leftArrowAriaLabelstring—Defines a string value that labels the left arrow in calendar header.
leftArrowAriaLabelledBystring—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.
monthDropdownAriaLabelstring—Defines a string value that labels the months dropdown in calendar header.
monthDropdownAriaLabelledBystring—Identifies the element that labels the months dropdown in calendar header.
numOfMonths1 | 21Allows 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
placeholderTextstring—Defines a placeholder of the field.
popoverPropsPopoverCommonProps—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.
readOnlyboolean—Specify whether date picker input is readOnly or not.
renderFooter() => ReactNode—Function which renders a provided node at the bottom of the Calendar.
rightArrowAriaLabelstring—Defines a string value that labels the right arrow in calendar header.
rightArrowAriaLabelledBystring—Identifies the element that labels the right arrow in calendar header.
rtlbooleanfalseSpecify 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.
shouldCloseOnSelectbooleantrueSpecify whether the calendar closes on day selection.
showDrawerOnMobilebooleantrueSpecifies whether the calendar opens in a bottom <Drawer/> when WixDesignSystemProvider has mobile enabled.
showMonthDropdownbooleanfalseDisplays a selectable monthDropdown.
showYearDropdownbooleanfalseDisplays a selectable yearDropdown.
size"small" | "medium" | "large"—Specifies the size of the input.
status"error" | "warning" | "loading"—Controls the status of a field.
statusMessageReactNode—Defines the status message to be displayed on status icon hover. If not given or empty, the tooltip won't be shown.
todayDate—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.
validateboolean—Enables internal input validation.
valueDate—Defines the selected date.
widthstring | number'150px'Sets the width of picker input in pixels or percentage.
yearDropdownAriaLabelstring—Defines a string value that labels the years dropdown in calendar header.
yearDropdownAriaLabelledBystring—Identifies the element that labels the years dropdown in calendar header.
zIndexnumber—Set a desired z-index for date picker popover.

Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

Changelog

  • 1.344.0 (2026-10-28) — maintenance release, no component-specific changes
  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.335.0 (2026-10-12) — feat: deleting the typed value no longer emits today's date through 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)
  • 1.334.0 (2026-10-08) — maintenance release, no component-specific changes
  • 1.332.0 (2026-10-05) — maintenance release, no component-specific changes
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.324.0 (2026-09-14) — maintenance release, no component-specific changes
  • 1.316.0 (2026-08-25) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.279.0 (2026-05-13) — maintenance release, no component-specific changes
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.272.0 (2026-04-27) — maintenance release, no component-specific changes
  • 1.271.0 (2026-04-22) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.241.0 (2025-12-17) — maintenance release, no component-specific changes
  • 1.239.0 (2025-12-12) — maintenance release, no component-specific changes
  • 1.225.0 (2025-11-07) — maintenance release, no component-specific changes
  • 1.220.0 (2025-09-29) — maintenance release, no component-specific changes
  • 1.213.0 (2025-08-19) — fix: uni driver (#15213)
  • 1.208.0 (2025-07-25) — fix: uni driver fix (#15113)
  • 1.203.0 (2025-07-01) — feat: add calendar props to date picker (#15023)
  • 1.195.0 (2025-06-03) — maintenance release, no component-specific changes
  • 1.184.0 (2025-04-30) — maintenance release, no component-specific changes
  • 1.181.0 (2025-04-18) — maintenance release, no component-specific changes
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.164.0 (2025-02-25) — fix: fix legacy testkit (#14556)
  • 1.162.0 (2025-02-17) — breaking: updated popover mechanism (#14531)
  • 1.144.0 (2024-12-03) — maintenance release, no component-specific changes
  • 1.143.0 (2024-11-25) — maintenance release, no component-specific changes
  • 1.139.0 (2024-11-07) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.128.0 (2024-09-19) — maintenance release, no component-specific changes
  • 1.121.0 (2024-08-13) — feat: add renderFooter prop (#14030)
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.109.2 (2024-06-17) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.98.0 (2024-03-15) — feat: add long dateStyle (#13444)
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?