1. Components
  2. Date and time
  3. Date Field

Date Field

A date field allows users to enter and edit date and time values using a keyboard.

<DateField aria-label="Meeting date" />

Installation

npx dotui-cli@latest add date-field

Usage

Use a DateField to allow users to enter and edit time values using a keyboard.

import { DateField } from "@/components/core/date-field";
 
<DateField label="Event date" description="Please select your event date." />;
import { DateFieldRoot, DateFieldInput } from "@/components/core/date-field";
import { Label, Description, FieldError } from "@/components/core/field";
 
<DateFieldRoot>
  <Label>Event date</Label>
  <DateFieldInput />
  <Description>Please select your event date.</Description>
  <FieldError />
</DateFieldRoot>;

Uncontrolled

An initial, uncontrolled value can be provided to the DateField using the defaultValue prop.

<DateField defaultValue={parseDate("2020-02-03")} />

Controlled

Use the value and onChange props to control the value of the input.

selected date: 2020-02-03

const [value, setValue] = React.useState(parseDate("2020-02-03"));
return <DateField value={value} onChange={setValue} />

Options

Label

A visual label can be provided for the DateField using the label prop or a hidden label using aria-label prop.

Meeting date
<DateField label="Meeting date" />
<DateField aria-label="Meeting date" />

Size

Use the size prop to control the size of the DateField.
The default variant is "md".

small (sm)
medium (md)
large (lg)
<DateField size="sm" />
<DateField size="md" />
<DateField size="lg" />

Prefix and suffix

To add additional context for the DateField, such as an icon, use the prefix and suffix props.

<DateField prefix={<CalendarIcon />} />
<DateField suffix={<CalendarIcon />} />

Description

A description can be supplied to DateField via the description prop. The description is always visible unless the isInvalid prop is true and an error message is provided.

Appointment datePlease select a date.
<DateField label="Appointment" description="Please select a date." />

Error message

An errorMessage can be supplied to DateField, which will be displayed when the isInvalid prop is set to true.

MeetingMeetings can't be scheduled in the past.
<DateField
  label="Meeting"
  isInvalid
  errorMessage="Meetings can't be scheduled in the past."
/>

Disabled

Use the isDisabled prop to disable the DateField.

Event date
<DateField label="Event date" isDisabled />

ReadOnly

The isReadOnly boolean prop makes the DateField's text content immutable. Unlike isDisabled, the DateField remains focusable and the contents can still be copied.

Event date
<DateField label="Event date" value={new CalendarDate(1980, 1, 1)} isReadOnly />

Required

Use the isRequired prop to mark the DateField as required. Use the necessityIndicator prop to control the visual style of the required state.

Event date
<DateField label="Event date" isRequired />

Value options

Time zones

DateField is time zone aware when a ZonedDateTime object is provided as the value.

<DateField
  aria-label="Meeting time"
  defaultValue={parseAbsoluteToLocal("2021-11-07T07:45:00Z")}
/>

Granularity

The granularity prop allows you to control the smallest unit that is displayed by DateField.

Hour
Minute
Second
<DateField
  label="Hour"
  granularity="hour"
  defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")}
/>
<DateField
  label="Minute"
  granularity="minute"
  defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")}
/>
<DateField
  label="Second"
  granularity="second"
  defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")}
/>

Format Options

Placeholder value

Use the placeholderValue prop to control the default values of each segment. The default value is midnight.

Meeting date
<DateField label="Meeting date" placeholderValue={new CalendarDate(1980, 1, 1)} />

Hide time zone

Use the hideTimeZone prop to hide the time zone abbreviation.

Appointment time
<DateField
  label="Appointment time"
  granularity="minute"
  defaultValue={parseZonedDateTime("2022-11-07T10:45[America/Los_Angeles]")}
  hideTimeZone
/>

Hour cycle

Use the hourCycle prop to control the hour cycle of the DateField.

<DateField aria-label="Meeting time" granularity="minute" hourCycle={24} />

Composition

If you need to customize things further, you can drop down to the composition level.

Meeting timePlease select a time between 9 AM and 5 PM.
<DateFieldRoot>
  <Label>Meeting time</Label>
  <DateFieldInput />
  <Description>Please select a time between 9 AM and 5 PM.</Description>
</DateFieldRoot>

API Reference

PropTypeDefaultDescription
minValueDateValue-The minimum allowed date that a user may select.
maxValueDateValue-The maximum allowed date that a user may select.
isDateUnavailable(date: DateValue) => boolean-Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
placeholderValueDateValue-A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle.
hourCycle12 | 24-Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
granularity'hour' | 'minute' | 'second'-Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.
hideTimeZonebooleanfalseWhether to hide the time zone abbreviation.
shouldForceLeadingZerosboolean-Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale.
isDisabledboolean-Whether the input is disabled.
isReadOnlyboolean-Whether the input can be selected but not changed by the user.
isRequiredboolean-Whether user input is required on the input before form submission.
isInvalidboolean-Whether the input value is invalid.
validate(value: MappedDateValue<DateValue>) => ValidationError | true | null | undefined-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.
autoFocusboolean-Whether the element should receive focus on render.
isOpenboolean-Whether the input value is invalid.
defaultOpenboolean-Whether the input value is invalid.
valueDateValue | null-The current value (controlled).
defaultValueDateValue | null-The default value (uncontrolled).
namestring-The name of the input element, used when submitting an HTML form.
validationBehavior'native' | 'aria''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.
childrenReactNode | (values: DateFieldRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode-The children of the component. A function may be provided to alter the children based on component state.
classNamestring-The CSS className for the element.
styleCSSProperties | (values: DateFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties-The inline style for the element. A function may be provided to compute the style based on component state.
EventTypeDescription
onFocus(e: FocusEvent<Target>) => voidHandler that is called when the element receives focus.
onBlur(e: FocusEvent<Target>) => voidHandler that is called when the element loses focus.
onFocusChange(isFocused: boolean) => voidHandler that is called when the element's focus status changes.
onKeyDown(e: KeyboardEvent) => voidHandler that is called when a key is pressed.
onKeyUp(e: KeyboardEvent) => voidHandler that is called when a key is released.
onOpenChange(isOpen: boolean) => voidHandler that is called when the overlay's open state changes.
onChange(value: MappedDateValue<DateValue>) => voidHandler that is called when the value changes.
Data attributeDescription
[data-invalid]Whether the date field is invalid.
[data-disabled]Whether the date field is disabled.

Accessibility

Keyboard interactions

KeyDescription
TabPlaces focus on the first segment. If a segment is already in focus, moves focus to the next segment. If last segment in in focus, moves focus to the next element in the page tab sequence.
ArrowRight ArrowLeftMoves focus between segments.
ArrowUp ArrowDownIncrements/decrements the value of the segment.
dotUI

Bringing singularity to the web.

Built by mehdibha. The source code is available on GitHub.