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.

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.

import { DateField, Inline } from '@marigold/components';export default () => (  <Inline space={2}>    <DateField label="Start Date" width={36} />    <DateField label="End Date" width={36} />  </Inline>);

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.

import { Inline, Select } from '@marigold/components';const nextTenYears = Array.from(  { length: 10 },  (_, i) => new Date().getFullYear() + i);export default () => (  <Inline space={1} alignY="bottom">    <Select      label="Expiration Date"      aria-label="Month"      placeholder="Month"      width={40}    >      <Select.Option id="01">January</Select.Option>      <Select.Option id="02">February</Select.Option>      <Select.Option id="03">March</Select.Option>      <Select.Option id="04">April</Select.Option>      <Select.Option id="05">May</Select.Option>      <Select.Option id="06">June</Select.Option>      <Select.Option id="07">July</Select.Option>      <Select.Option id="08">August</Select.Option>      <Select.Option id="09">September</Select.Option>      <Select.Option id="10">October</Select.Option>      <Select.Option id="11">November</Select.Option>      <Select.Option id="12">December</Select.Option>    </Select>    <Select aria-label="Year" placeholder="Year" width={28}>      {nextTenYears.map(year => (        <Select.Option key={year} id={year.toString()}>          {year}        </Select.Option>      ))}    </Select>  </Inline>);

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.

import { parseAbsoluteToLocal, parseDateTime } from '@internationalized/date';import { DateField, Stack } from '@marigold/components';export default () => (  <Stack space={8}>    <DateField      label="Date and Time"      granularity="second"      defaultValue={parseDateTime('2025-07-23T08:29')}    />    <DateField      label="Date and Time with Timezone"      granularity="second"      defaultValue={parseAbsoluteToLocal('2024-03-15T05:25:21Z')}    />  </Stack>);

Props

DateField

Alternative components

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

Related