DateField

The <DateField> allows users to enter and edit date values using a keyboard. Each part of a date value, including the calendar date, time, and timezone, is displayed in an individually editable segment. These segments are individually focusable and editable by the user, by typing or using the arrow keys to increment and decrement the value. This approach allows values to be formatted and parsed correctly regardless of the locale or date format, and offers an easy and error-free way to edit all aspects of a date using the keyboard.

Anatomy

A <DateField> consists of a label and a group of segments representing each unit of a date, such as the calendar date, time, and timezone.

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

Property	Type	Description
`variant`	`-`	The available variants of this component.
`size`	`-`	The available sizes of this component.

Usage

Date inputs play a critical role in many user flows such as reserving tickets, scheduling appointments, setting deadlines, or logging activity. These are moments where users expect clarity, guidance, and precision.

Use a date field when users need to select a specific day or time, when the date will be used for sorting or calculations, or when consistent formatting and validation are important. It is especially helpful in workflows where precision matters, like booking systems, calendars, or reporting tools. A structured input helps prevent common errors like swapped day and month formats, forgotten timezones, or typos.

Preview

Code

Start Date

End Date

Partial Dates

Avoid using a date field when only part of the date is needed, such as just the month or year, or when the date is vague, optional, or generated by the system. In those cases, a simpler input may better match user expectations and reduce friction.

For example, if only the month and year are required, such as when entering a credit card expiration date, a dedicated month/year input or two dropdowns is more appropriate. This simplifies the interaction and avoids the added complexity of a full date field. The following demo shows how this can be achieved without using a date field.

Preview

Code

Expiration Date

Granularity

Adjust the level of granularity in a date field based on what the user needs to provide. For example, if users only need to select a day (like for a birthday), there’s no need to show time or timezone fields. If the context involves scheduling or deadlines, including time, and sometimes timezone, may be essential.

Use only as much detail as the use case requires. This keeps the input focused, reduces user effort, and avoids unnecessary complexity.

By default, the granularity is set to day, but it can be adjusted to include time and even show timezone when needed.

Preview

Code

Date and Time

0723202582900AM

Date and Time with Timezone

0315202452521AMUTC

Working with localized Dates

Use helpers from the @internationalized/date package to provide date values. This ensures correct handling of calendars, time zones, and localization across different regions.

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 DateField stories

action?

ReactElement<any, string | JSXElementConstructor<any>>;

Optional element (e.g., button or icon) rendered inside the DateField.

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.

autoComplete?

string;

Describes the type of autocomplete functionality the input should provide if any. See MDN.

autoFocus?

boolean;

Whether the element should receive focus on render.

defaultValue?

DateValue | null;

The default value (uncontrolled).

description?

ReactNode;

A helpful text.

dir?

string;

disabled?

boolean;

If true, the date field 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.

form?

string;

The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.

granularity?

Granularity;

Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.

hidden?

boolean;

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.

inert?

boolean;

isDateUnavailable?

(date: DateValue) => boolean;

Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.

label?

ReactNode;

Specifies the label of the field.

lang?

string;

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.

onAnimationEnd?

AnimationEventHandler<HTMLDivElement>;

onAnimationEndCapture?

AnimationEventHandler<HTMLDivElement>;

onAnimationIteration?

AnimationEventHandler<HTMLDivElement>;

onAnimationIterationCapture?

AnimationEventHandler<HTMLDivElement>;

onAnimationStart?

AnimationEventHandler<HTMLDivElement>;

onAnimationStartCapture?

AnimationEventHandler<HTMLDivElement>;

onAuxClick?

MouseEventHandler<HTMLDivElement>;

onAuxClickCapture?

MouseEventHandler<HTMLDivElement>;

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.

onClick?

MouseEventHandler<HTMLDivElement>;

onClickCapture?

MouseEventHandler<HTMLDivElement>;

onContextMenu?

MouseEventHandler<HTMLDivElement>;

onContextMenuCapture?

MouseEventHandler<HTMLDivElement>;

onDoubleClick?

MouseEventHandler<HTMLDivElement>;

onDoubleClickCapture?

MouseEventHandler<HTMLDivElement>;

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.

onGotPointerCapture?

PointerEventHandler<HTMLDivElement>;

onGotPointerCaptureCapture?

PointerEventHandler<HTMLDivElement>;

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.

onLostPointerCapture?

PointerEventHandler<HTMLDivElement>;

onLostPointerCaptureCapture?

PointerEventHandler<HTMLDivElement>;

onMouseDown?

MouseEventHandler<HTMLDivElement>;

onMouseDownCapture?

MouseEventHandler<HTMLDivElement>;

onMouseEnter?

MouseEventHandler<HTMLDivElement>;

onMouseLeave?

MouseEventHandler<HTMLDivElement>;

onMouseMove?

MouseEventHandler<HTMLDivElement>;

onMouseMoveCapture?

MouseEventHandler<HTMLDivElement>;

onMouseOut?

MouseEventHandler<HTMLDivElement>;

onMouseOutCapture?

MouseEventHandler<HTMLDivElement>;

onMouseOver?

MouseEventHandler<HTMLDivElement>;

onMouseOverCapture?

MouseEventHandler<HTMLDivElement>;

onMouseUp?

MouseEventHandler<HTMLDivElement>;

onMouseUpCapture?

MouseEventHandler<HTMLDivElement>;

onPointerCancel?

PointerEventHandler<HTMLDivElement>;

onPointerCancelCapture?

PointerEventHandler<HTMLDivElement>;

onPointerDown?

PointerEventHandler<HTMLDivElement>;

onPointerDownCapture?

PointerEventHandler<HTMLDivElement>;

onPointerEnter?

PointerEventHandler<HTMLDivElement>;

onPointerLeave?

PointerEventHandler<HTMLDivElement>;

onPointerMove?

PointerEventHandler<HTMLDivElement>;

onPointerMoveCapture?

PointerEventHandler<HTMLDivElement>;

onPointerOut?

PointerEventHandler<HTMLDivElement>;

onPointerOutCapture?

PointerEventHandler<HTMLDivElement>;

onPointerOver?

PointerEventHandler<HTMLDivElement>;

onPointerOverCapture?

PointerEventHandler<HTMLDivElement>;

onPointerUp?

PointerEventHandler<HTMLDivElement>;

onPointerUpCapture?

PointerEventHandler<HTMLDivElement>;

onScroll?

UIEventHandler<HTMLDivElement>;

onScrollCapture?

UIEventHandler<HTMLDivElement>;

onTouchCancel?

TouchEventHandler<HTMLDivElement>;

onTouchCancelCapture?

TouchEventHandler<HTMLDivElement>;

onTouchEnd?

TouchEventHandler<HTMLDivElement>;

onTouchEndCapture?

TouchEventHandler<HTMLDivElement>;

onTouchMove?

TouchEventHandler<HTMLDivElement>;

onTouchMoveCapture?

TouchEventHandler<HTMLDivElement>;

onTouchStart?

TouchEventHandler<HTMLDivElement>;

onTouchStartCapture?

TouchEventHandler<HTMLDivElement>;

onTransitionCancel?

TransitionEventHandler<HTMLDivElement>;

onTransitionCancelCapture?

TransitionEventHandler<HTMLDivElement>;

onTransitionEnd?

TransitionEventHandler<HTMLDivElement>;

onTransitionEndCapture?

TransitionEventHandler<HTMLDivElement>;

onTransitionRun?

TransitionEventHandler<HTMLDivElement>;

onTransitionRunCapture?

TransitionEventHandler<HTMLDivElement>;

onTransitionStart?

TransitionEventHandler<HTMLDivElement>;

onTransitionStartCapture?

TransitionEventHandler<HTMLDivElement>;

onWheel?

WheelEventHandler<HTMLDivElement>;

onWheelCapture?

WheelEventHandler<HTMLDivElement>;

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 field is readOnly.

Defaults to:

"false"

ref?

Ref<HTMLInputElement>;

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 field is required.

Defaults to:

"false"

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.

translate?

"yes" | "no";

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

Defaults to:

'full'

Alternative components

DatePicker: a user interface element that allows users to select a date from a calendar.

Building forms

Learn how to build forms.

Form Fields

Learn how to build forms.

Last update: 10 days ago

Appearance

Variant

Size

The selected theme does not has any options for "variant" and "size".

Event Date

Property

Type

Description

variant

-

The available variants of this component.

size

-

The available sizes of this component.

Usage

Preview

Code

Start Date

End Date

Preview

Code

Expiration Date

Use only as much detail as the use case requires. This keeps the input focused, reduces user effort, and avoids unnecessary complexity.

By default, the granularity is set to day, but it can be adjusted to include time and even show timezone when needed.

Preview

Code

Date and Time

0723202582900AM

Date and Time with Timezone

0315202452521AMUTC

Working with localized Dates

Use helpers from the @internationalized/date package to provide date values. This ensures correct handling of calendars, time zones, and localization across different regions.

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 DateField stories

action?

ReactElement<any, string | JSXElementConstructor<any>>;

Optional element (e.g., button or icon) rendered inside the DateField.

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.

autoComplete?

string;

Describes the type of autocomplete functionality the input should provide if any. See MDN.

autoFocus?

boolean;

Whether the element should receive focus on render.

defaultValue?

DateValue | null;

The default value (uncontrolled).

description?

ReactNode;

A helpful text.

dir?

string;

disabled?

boolean;

If true, the date field 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.

form?

string;

The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.

granularity?

Granularity;

Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.

hidden?

boolean;

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.

inert?

boolean;

isDateUnavailable?

(date: DateValue) => boolean;

Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.

label?

ReactNode;

Specifies the label of the field.

lang?

string;

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.

onAnimationEnd?

AnimationEventHandler<HTMLDivElement>;

onAnimationEndCapture?

AnimationEventHandler<HTMLDivElement>;

onAnimationIteration?

AnimationEventHandler<HTMLDivElement>;

onAnimationIterationCapture?

AnimationEventHandler<HTMLDivElement>;

onAnimationStart?

AnimationEventHandler<HTMLDivElement>;

onAnimationStartCapture?

AnimationEventHandler<HTMLDivElement>;

onAuxClick?

MouseEventHandler<HTMLDivElement>;

onAuxClickCapture?

MouseEventHandler<HTMLDivElement>;

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.

onClick?

MouseEventHandler<HTMLDivElement>;

onClickCapture?

MouseEventHandler<HTMLDivElement>;

onContextMenu?

MouseEventHandler<HTMLDivElement>;

onContextMenuCapture?

MouseEventHandler<HTMLDivElement>;

onDoubleClick?

MouseEventHandler<HTMLDivElement>;

onDoubleClickCapture?

MouseEventHandler<HTMLDivElement>;

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.

onGotPointerCapture?

PointerEventHandler<HTMLDivElement>;

onGotPointerCaptureCapture?

PointerEventHandler<HTMLDivElement>;

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.

onLostPointerCapture?

PointerEventHandler<HTMLDivElement>;

onLostPointerCaptureCapture?

PointerEventHandler<HTMLDivElement>;

onMouseDown?

MouseEventHandler<HTMLDivElement>;

onMouseDownCapture?

MouseEventHandler<HTMLDivElement>;

onMouseEnter?

MouseEventHandler<HTMLDivElement>;

onMouseLeave?

MouseEventHandler<HTMLDivElement>;

onMouseMove?

MouseEventHandler<HTMLDivElement>;

onMouseMoveCapture?

MouseEventHandler<HTMLDivElement>;

onMouseOut?

MouseEventHandler<HTMLDivElement>;

onMouseOutCapture?

MouseEventHandler<HTMLDivElement>;

onMouseOver?

MouseEventHandler<HTMLDivElement>;

onMouseOverCapture?

MouseEventHandler<HTMLDivElement>;

onMouseUp?

MouseEventHandler<HTMLDivElement>;

onMouseUpCapture?

MouseEventHandler<HTMLDivElement>;

onPointerCancel?

PointerEventHandler<HTMLDivElement>;

onPointerCancelCapture?

PointerEventHandler<HTMLDivElement>;

onPointerDown?

PointerEventHandler<HTMLDivElement>;

onPointerDownCapture?

PointerEventHandler<HTMLDivElement>;

onPointerEnter?

PointerEventHandler<HTMLDivElement>;

onPointerLeave?

PointerEventHandler<HTMLDivElement>;

onPointerMove?

PointerEventHandler<HTMLDivElement>;

onPointerMoveCapture?

PointerEventHandler<HTMLDivElement>;

onPointerOut?

PointerEventHandler<HTMLDivElement>;

onPointerOutCapture?

PointerEventHandler<HTMLDivElement>;

onPointerOver?

PointerEventHandler<HTMLDivElement>;

onPointerOverCapture?

PointerEventHandler<HTMLDivElement>;

onPointerUp?

PointerEventHandler<HTMLDivElement>;

onPointerUpCapture?

PointerEventHandler<HTMLDivElement>;

onScroll?

UIEventHandler<HTMLDivElement>;

onScrollCapture?

UIEventHandler<HTMLDivElement>;

onTouchCancel?

TouchEventHandler<HTMLDivElement>;

onTouchCancelCapture?

TouchEventHandler<HTMLDivElement>;

onTouchEnd?

TouchEventHandler<HTMLDivElement>;

onTouchEndCapture?

TouchEventHandler<HTMLDivElement>;

onTouchMove?

TouchEventHandler<HTMLDivElement>;

onTouchMoveCapture?

TouchEventHandler<HTMLDivElement>;

onTouchStart?

TouchEventHandler<HTMLDivElement>;

onTouchStartCapture?

TouchEventHandler<HTMLDivElement>;

onTransitionCancel?

TransitionEventHandler<HTMLDivElement>;

onTransitionCancelCapture?

TransitionEventHandler<HTMLDivElement>;

onTransitionEnd?

TransitionEventHandler<HTMLDivElement>;

onTransitionEndCapture?

TransitionEventHandler<HTMLDivElement>;

onTransitionRun?

TransitionEventHandler<HTMLDivElement>;

onTransitionRunCapture?

TransitionEventHandler<HTMLDivElement>;

onTransitionStart?

TransitionEventHandler<HTMLDivElement>;

onTransitionStartCapture?

TransitionEventHandler<HTMLDivElement>;

onWheel?

WheelEventHandler<HTMLDivElement>;

onWheelCapture?

WheelEventHandler<HTMLDivElement>;

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 field is readOnly.

Defaults to:

"false"

ref?

Ref<HTMLInputElement>;

required?

boolean;

If true, the date field is required.

Defaults to:

"false"

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;

translate?

"yes" | "no";

validate?

(value: DateValue) => true | ValidationError | null;

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

Defaults to:

'full'