DatePicker

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.

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.

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.

import { DatePicker } from '@marigold/components';export default () => <DatePicker label="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 .

import { CalendarDate } from '@internationalized/date';import { DatePicker } from '@marigold/components';export default () => (  <DatePicker    label="Event Date"    description="Choose a date for your ticket purchase. Dates must be between June 5, 2025, and June 20, 2025."    minValue={new CalendarDate(2025, 6, 5)}    maxValue={new CalendarDate(2025, 6, 20)}  />);

Controlled

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

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

import type { DateValue } from '@internationalized/date';import { parseDate } from '@internationalized/date';import { useState } from 'react';import { DatePicker, Stack } from '@marigold/components';export default () => {  const [value, setValue] = useState<DateValue>(parseDate('2023-10-29'));  return (    <Stack space={3}>      <DatePicker        label="Ticket Date"        value={value}        onChange={newValue => setValue(newValue!)}      />      <pre>        <strong>Current Selected Date: </strong>        {`Day: ${value.day} Month: ${value.month} Year: ${value.year}`}      </pre>    </Stack>  );};

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.

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.

import type { DateValue } from '@internationalized/date';import { parseAbsoluteToLocal } from '@internationalized/date';import { useState } from 'react';import { DatePicker } from '@marigold/components';export default () => {  const date = new Date().toISOString();  const [value, setValue] = useState<DateValue>(parseAbsoluteToLocal(date)!);  return (    <DatePicker      label="Date"      value={value}      onChange={newValue => setValue(newValue!)}    />  );};

Paste Support

The <DatePicker> supports pasting date values from the clipboard. Users can copy dates in common formats and paste them directly into the date picker field. The component automatically parses and validates the pasted content.

Supported date formats:

• ISO format: 2023-12-25
• European format: 25.12.2023 or 25/12/2023
• US format: 12/25/2023 or 12-25-2023

Invalid dates or unrecognized formats are ignored, ensuring data integrity.

import { DatePicker, Stack, Text } from '@marigold/components';export default function () {  return (    <Stack space={4}>      <Text size="small" variant="info">        Try pasting a date in yyyy-mm-dd format (e.g., &quot;2025-09-24&quot;)      </Text>      <DatePicker        label="Scheduled Date"        description="You can paste dates directly into this field"      />    </Stack>  );}

Props

DatePicker

Alternative components

• DateField: Allows users to input a date directly.

Related