DateField

Patterns

Date Field With Popover Calendar

When to use:

• A standard form field should allow both typing and picking.
• The calendar should appear on demand instead of staying visible.

Composition notes:

• Keep DateFieldInput as the primary surface and label it.
• Mount DateFieldCalendar inside PopoverContent and use DateFieldTriggerIconButton with an aria-label as the trigger.

Trade-offs:

• Saves layout space.
• Requires overlay testing inside dialogs, drawers, and scroll containers.

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

Date Field In Validation-Heavy Forms

When to use:

• The date must participate in submit validation.
• Error copy and helper text matter more than visual calendar exploration.

Composition notes:

• Use native required and pattern on DateFieldInput for presence and completeness; min and max are already enforced while typing.
• disabledDates is enforced only in the calendar, so repeat that rule in submit validation.
• Show the error with error on the root and HelperText error, linked through aria-describedby.

Trade-offs:

• Native constraint validation with no extra library.
• name on the input submits the typed text; to submit the ISO day, mirror onChangeValue into a hidden input as in Form/Integration.

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

Date Field Inside Modal Workflows

When to use:

• Scheduling or review flows live inside Dialog, Drawer, or Sheet.
• The calendar still needs on-demand access.

Composition notes:

• Test focus, dismissal, and stacking with the parent overlay.
• Keep the calendar compact enough for the parent container.

Trade-offs:

• Preserves the existing modal flow.
• Increases overlay coordination complexity.

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

Date Field In A Non-Gregorian Calendar

When to use:

• Users type and read dates in a Persian, Hebrew, Japanese, Buddhist, Islamic, or other calendar.

Composition notes:

• Create the calendar once with createCalendarSystem, outside the component (see Dates And Calendar Systems), and pass it to the calendar prop of the root, together with locale.
• Typing is validated in that calendar, for example day 31 of Persian month 6 or Hebrew month 13; min and max stay ISO YYYY-MM-DD strings.

Trade-offs:

• Native month lengths and leap months without changing the stored value.
• Month lengths and eras come from the Intl data of the runtime.

import { useState } from 'react';
import { createCalendarSystem } from '@vega-ui/i18n';
import {
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,
  CalendarPrevButton,

Comparison

Quick Decision Rule

Use DateField when the value is a single calendar date and users should be able to type it, pick it, or both.

DateField vs DateRangeField

Use DateField when one date is stored.

Use DateRangeField when the start and end dates must stay connected as one control.

Main trade-off: DateField is simpler to label and validate, while DateRangeField reduces coordination mistakes across two related values.

DateField vs DateTimeField

Use DateField when time is irrelevant to the stored value.

Use DateTimeField when date and time together define the final value.

Main trade-off: DateField is easier to input and review, while DateTimeField captures a complete timestamp.

DateField vs Calendar

Use DateField when users need typed entry and a form-like field.

Use Calendar when the interface is primarily visual date picking without field-style text entry.

Main trade-off: DateField fits forms better, while Calendar is stronger for always-visible date selection.

Choose This Component When

• The value is a single date.
• Users may type the date directly.
• The control belongs in a form row or settings panel.
• The calendar is optional support, not the whole interaction model.

Do Not Choose This Component When

• The feature needs a start and end date pair.
• The stored value must include time.
• The UI should present a fully visible calendar instead of an input-led field.

Troubleshooting

Calendar Button Opens Nothing

Symptom

The trigger icon button renders, but clicking it never shows a calendar.

Likely Cause

DateFieldTriggerIconButton was rendered without a surrounding Popover or without DateFieldCalendar inside the overlay.

How To Verify

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

Fix

Compose the trigger and calendar through Popover, inside DateField.

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

Typed Value Looks Wrong

Symptom

The input format shown to users does not match parsing behavior.

Likely Cause

format or separator does not match the date copy used in labels, hints, and validation messages.

How To Verify

• Compare the configured format with the visible form hint.
• Type a representative value and inspect how it is interpreted.

Fix

Keep visible guidance, parsing rules, and validation copy aligned around the same format.

Submitted Value Is Not An ISO Date

Symptom

The form submits 15.01.2026 instead of 2026-01-15.

Likely Cause

DateFieldInput is a native input, and name submits its typed text.

How To Verify

• Read the field from FormData in the submit handler.

Fix

Take the ISO day from onChangeValue on the root instead of the text. To submit it with the form, drop name from the input and put it on a hidden input that holds the day, as in Form/Integration.

Disabled Dates Can Still Be Typed

Symptom

The calendar blocks some days, but typing one of them is accepted and submitted.

Likely Cause

min and max clamp typed dates, but disabledDates applies only to the calendar.

How To Verify

• Type a disabled day and submit the form.

Fix

Check the same disabledDates rule in submit validation and on the server.