DateTimeField

Patterns

Timestamp Field With Popover Calendar

When to use:

• Users need one field that captures both date and time.
• The calendar should open on demand instead of staying visible.

Composition notes:

• Keep DateTimeFieldInput as the primary surface and label it.
• Mount DateTimeFieldCalendar inside PopoverContent; picking a day keeps the typed time.

Trade-offs:

• Keeps the form compact.
• Requires clear formatting and timezone guidance.

import {
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,
  CalendarPrevButton,
  CalendarViewButton,
  CalendarViewButtonGroup,

Timestamp Field In Scheduling Forms

When to use:

• Publishing, reminders, or execution schedules depend on one timestamp.
• Validation and serialization happen close to submit.

Composition notes:

• Keep helper text explicit about timezone and expected format.
• Align min, max, and timeStep with scheduling business rules; min and max clamp typed values, timeStep only drives arrow-key stepping.
• name on the input submits the typed text; to send the YYYY-MM-DDTHH:mm value, mirror onChangeValue into a hidden input as in Form/Integration.

Trade-offs:

• Strong timestamp control in one field row.
• More validation and copy complexity than a plain date field.

import { FormEvent, useState } from 'react';
import {
  Button,
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,
  CalendarPrevButton,

Timestamp Field Inside Mobile-First Sheets

When to use:

• Scheduling happens inside Sheet or another constrained overlay.
• The user still needs a calendar affordance.

Composition notes:

• Test popover placement and scrolling inside the parent overlay.
• Keep the field concise enough for narrow layouts.

Trade-offs:

• Preserves modal context.
• Increases overlay and focus coordination complexity.

import { CSSProperties, useState } from 'react';
import { XIcon } from '@vega-ui/icons';
import {
  Button,
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,

Comparison

Quick Decision Rule

Use DateTimeField when the final stored value must include both a date and a time.

DateTimeField vs DateField

Use DateTimeField when time matters to the saved value.

Use DateField when only the calendar date matters.

Main trade-off: DateTimeField captures a complete timestamp, but it is heavier to type, validate, and explain.

DateTimeField vs DateRangeField

Use DateTimeField when the feature centers on one scheduled moment.

Use DateRangeField when the feature centers on a span.

Main trade-off: timestamps represent one instant; ranges represent duration.

DateTimeField vs Calendar

Use DateTimeField when typed entry and form semantics are important.

Use Calendar when the UI is primarily a visual date picker.

Main trade-off: DateTimeField is stronger for form workflows, while Calendar is stronger for visible date browsing.

DateTimeField vs TimeField + DateField

Use DateTimeField when one timestamp should be validated, labeled, and serialized as one value.

Use separate fields when date and time are intentionally edited or submitted independently.

Main trade-off: DateTimeField reduces coordination drift, while split fields can fit specialized workflows better.

Choose This Component When

• The product stores one timestamp.
• Users may type both date and time.
• Validation and copy must stay in one field row.

Do Not Choose This Component When

• The feature needs only a date.
• The feature needs a start and end span.
• The UI should present a fully visible calendar-first picker instead of a field-led control.

Troubleshooting

Typed Timestamp Does Not Match Product Expectation

Symptom

Users enter a date and time, but the resulting scheduled value is not what the feature expects.

Likely Cause

The field configuration and product timezone or serialization rules are not aligned.

How To Verify

• Compare visible input guidance with the saved payload.
• Inspect whether timezone conversion happens before or after submit.

Fix

Keep timestamp formatting, timezone rules, and payload serialization explicit in the feature flow.

Calendar Trigger Opens Nothing

Symptom

The icon button renders, but the calendar never appears.

Likely Cause

DateTimeFieldTriggerIconButton was rendered without Popover composition or without DateTimeFieldCalendar inside the overlay.

How To Verify

• Check whether the trigger is wrapped in PopoverTrigger.
• Check whether PopoverContent contains DateTimeFieldCalendar.

Fix

Compose the trigger and calendar through Popover.

Time Step Feels Wrong

Symptom

Users can enter times that do not match the intended schedule granularity.

Likely Cause

timeStep does not reflect the real business constraint for the feature.

How To Verify

• Compare allowed times with product requirements.
• Test representative values such as quarter-hour or half-hour slots.

Fix

Configure timeStep to match the real scheduling rule and validate it consistently on submit.