DatePicker

Component used to pick date value.

The <DatePicker> component is a user interface element that allows users to select a date from a calendar.

The typical practice is to provide a date picker and when you click on calendar button it pops up a calendar below the date field, allowing the user to populate the field with an appropriate date.

Anatomy

The Label defines the purpose of the Date Field, where users can enter a date directly. Tapping the Calendar Button opens a calendar view with a Header for selecting the month and year, and Next/Previous Buttons for easy month navigation.

Anatomy of datepicker

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Variant
Size
The selected theme does not has any options for "variant" and "size".
Event Date
PropertyTypeDescription
variant-The available variants of this component.
size-The available sizes of this component.

Usage

<DatePicker> is used when you need users to select a date accurately, like for booking events, scheduling appointments, or setting deadlines. It’s ideal when date formats might vary, as it standardizes input and reduces mistakes because its visual clarity, format consistency and accuracy. DatePickers are also helpful when users might need guidance on valid date ranges, like selecting only future dates for reservations. Avoid using it for casual date entries where a simple text field would suffice.

Basic Usage (uncontrolled)

This example shows a regular <DatePicker> without any special props.

Date

Min/Max Values

The minValue and maxValue props are used to perform built-in validation. This prevents the user from selecting dates outside the valid range in the calendar .

Event Date
Choose a date for your ticket purchase. Dates must be between June 5, 2025, and June 20, 2025.

Controlled

The value and onChange props can be used to control the DatePicker.

Ticket Date
Current Selected Date: Day: 29 Month: 10 Year: 2023

Using a Date Object

When using a datepicker, relying on the standard JavaScript Date object for its value can result in timezone inconsistencies and incorrect date display. That's why the datepicker uses a specific DateValue type from @internationalized/date instead. This library handles correct international date manipulation across calendars, time zones, and other localization concerns.

@internationalized/date

@internationalized/date is a peer dependency. If it's not already in your project, you'll need to install it.

The simplest way to parse a Date for the datepicker is by using parseAbsoluteToLocal. This function converts an absolute date and time into the current user's local time zone. If you're already using a date library like date-fns, you can also utilizing parseDate. Ensure that you only pass the date part to parseDate, excluding the time and timezone information.

Date

Props

Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!
View DatePicker stories
aria-describedby?
string;
Identifies the element (or elements) that describes the object.
aria-details?
string;
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-label?
string;
Defines a string value that labels the current element.
aria-labelledby?
string;
Identifies the element (or elements) that labels the current element.
autoFocus?
boolean;
Whether the element should receive focus on render.
children?
ReactNode |
  ((values: DatePickerRenderProps & { defaultChildren: ReactNode }) => ReactNode);
The children of the component. A function may be provided to alter the children based on component state.
dateUnavailable?
(date: DateValue) => boolean;
Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
defaultOpen?
boolean;
Whether the overlay is open by default (uncontrolled).
defaultValue?
DateValue | null;
The default value (uncontrolled).
description?
ReactNode;
A helpful text.
disabled?
boolean;
If true, the date picker is disabled.
Defaults to: 
"false"
error?
boolean;
If true, the field is considered invalid and if set the errorMessage is shown instead of the description.
Defaults to: 
"false"
errorMessage?
ReactNode | ((v: ValidationResult) => ReactNode);
An error message.
firstDayOfWeek?
"sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
The day that starts the week.
granularity?
Granularity;
Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.
Defaults to: 
"day"
hideTimeZone?
boolean;
Whether to hide the time zone abbreviation.
Defaults to: 
"false"
hourCycle?
12 | 24;
Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
id?
string;
The element's unique identifier. See MDN.
label?
ReactNode;
Specifies the label of the field.
maxValue?
DateValue | null;
The maximum allowed date that a user may select.
minValue?
DateValue | null;
The minimum allowed date that a user may select.
name?
string;
The name of the input element, used when submitting an HTML form. See MDN.
onBlur?
(e: FocusEvent<Element, Element>) => void;
Handler that is called when the element loses focus.
onChange?
(value: DateValue | null) => void;
Handler that is called when the value changes.
onFocus?
(e: FocusEvent<Element, Element>) => void;
Handler that is called when the element receives focus.
onFocusChange?
(isFocused: boolean) => void;
Handler that is called when the element's focus status changes.
onKeyDown?
(e: KeyboardEvent) => void;
Handler that is called when a key is pressed.
onKeyUp?
(e: KeyboardEvent) => void;
Handler that is called when a key is released.
onOpenChange?
(isOpen: boolean) => void;
Handler that is called when the overlay's open state changes.
open?
boolean;
Whether the calendar is open by default (controlled).
Defaults to: 
"false"
pageBehavior?
PageBehavior;
Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
Defaults to: 
"visible"
placeholderValue?
DateValue | null;
A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
readOnly?
boolean;
If true, the date picker is readOnly.
Defaults to: 
"false"
ref?
Ref<HTMLDivElement>;
Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}
required?
boolean;
If true, the date picker is required.
Defaults to: 
"false"
shouldCloseOnSelect?
boolean | (() => boolean);
Determines whether the date picker popover should close automatically when a date is selected.
Defaults to: 
"true"
shouldForceLeadingZeros?
boolean;
Whether to always show leading zeros in the month, day, and hour fields. By default, this is determined by the user's locale.
slot?
string | null;
A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.
validate?
(value: DateValue) => true | ValidationError | null;
A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
validationBehavior?
"native" | "aria";
Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
Defaults to: 
'native'
value?
DateValue | null;
The current value (controlled).
width?
WidthProp;
Sets the width of the field. You can see allowed tokens here: https://tailwindcss.com/docs/width

Alternative components

  • DateField: Allows users to input a date directly.

Related

Building forms
Learn how to build forms.
Form Fields
Learn how to build forms.
Last update: 6 months ago