# DateField
## Summary
`DateField` is a [compound component](https://vega-ui.dev/docs/glossary/#compound-component) for single-date entry that combines typed input, optional calendar selection, and field-level constraints in one control. It is the field-first date-input layer, with the calendar acting as an optional picking aid rather than the primary abstraction.
## Imports
```tsx
import {
DateField,
DateFieldInput,
DateFieldCalendar,
DateFieldTriggerIconButton,
type DateFieldProps,
} from '@vega-ui/react';
```
## Exported Types
- `DateFieldProps`
- `DateFieldInputProps`
- `DateFieldCalendarProps`
- `DateFieldTriggerIconButtonProps`
## Minimal Composition
```tsx
import {
CalendarContent,
CalendarDay,
CalendarDays,
CalendarHeader,
CalendarMonth,
CalendarMonthLabel,
CalendarMonths,
CalendarNextButton,
CalendarPrevButton,
CalendarViewButton,
CalendarViewButtonGroup,
CalendarWeekday,
CalendarWeekdays,
CalendarWeeks,
CalendarYear,
CalendarYearLabel,
CalendarYears,
DateField,
DateFieldCalendar,
DateFieldInput,
DateFieldTriggerIconButton,
Popover,
PopoverContent,
PopoverTrigger,
} from '@vega-ui/react';
export default function MinimalComposition() {
return (
);
}
```
## Required Parts
- `DateField`: root state and formatting owner
- `DateFieldInput`: typed date entry surface
## Optional Parts
- `DateFieldTriggerIconButton`: calendar trigger affordance
- `DateFieldCalendar`: visual picker content, usually mounted in `Popover`
## Composition Order
1. `DateField`
2. `DateFieldInput`
3. `Popover`
4. `DateFieldTriggerIconButton`
5. `DateFieldCalendar`
## Variants
- Input-only versus input-plus-calendar composition
- Trigger-driven picker versus typed entry only
- Constrained state through `min`, `max`, and `disabledDates`
## Edge Cases
- Locale, timezone, and serialization rules still belong to the consumer.
- Partial typed values are common during editing and should not be treated as final values.
- Overlay behavior should be tested inside dialogs, drawers, and scroll containers.
- The same business rule should drive typed validation and calendar blocking; they should not drift into two different policies.
## Common Mistakes
- Passing `Date` objects or display-format strings to `min` / `max` instead of ISO `YYYY-MM-DD` strings.
- Assuming the field solves timezone policy by itself.
- Leaving the trigger icon button unlabeled in accessible flows.
- Treating `min`, `max`, and `disabledDates` as visual hints instead of validation rules.
## Examples
### Basic
#### Basic: typed date with a calendar popover
A labelled field where users type a date or pick it in a popover calendar. `defaultValue` on the root is an ISO `YYYY-MM-DD` day; the input shows it in `format`, and the helper text tells users which format to type.
```tsx
import {
CalendarContent,
CalendarDay,
CalendarDays,
CalendarHeader,
CalendarMonth,
CalendarMonthLabel,
CalendarMonths,
CalendarNextButton,
CalendarPrevButton,
CalendarViewButton,
CalendarViewButtonGroup,
CalendarWeekday,
CalendarWeekdays,
CalendarWeeks,
CalendarYear,
CalendarYearLabel,
CalendarYears,
DateField,
DateFieldCalendar,
DateFieldInput,
DateFieldTriggerIconButton,
HelperText,
Label,
Popover,
PopoverContent,
PopoverTrigger,
} from '@vega-ui/react';
export const locales = ['en-US', 'ru-RU', 'ar-EG', 'he-IL'];
export default function TypedDateWithACalendarPopover({ locale = 'en-US' }: { locale?: string }) {
return (
Type the date as dd.mm.yyyy or pick it in the calendar.
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: preset dates
`value` and `onChangeValue` on the root keep the ISO day in parent state. Buttons set it from outside and the input shows it in `format`; while the typed text is incomplete the value is `''`.
```tsx
import { useState } from 'react';
import {
Button,
CalendarContent,
CalendarDay,
CalendarDays,
CalendarHeader,
CalendarMonth,
CalendarMonthLabel,
CalendarMonths,
CalendarNextButton,
CalendarPrevButton,
CalendarViewButton,
CalendarViewButtonGroup,
CalendarWeekday,
CalendarWeekdays,
CalendarWeeks,
CalendarYear,
CalendarYearLabel,
CalendarYears,
DateField,
DateFieldCalendar,
DateFieldInput,
DateFieldTriggerIconButton,
Label,
Popover,
PopoverContent,
PopoverTrigger,
Text,
} from '@vega-ui/react';
const toISODate = (date: Date) => {
const month = String(date.getMonth() + 1).padStart(2, '0');
const day = String(date.getDate()).padStart(2, '0');
return `${date.getFullYear()}-${month}-${day}`;
};
const daysFromToday = (days: number) => {
const date = new Date();
date.setDate(date.getDate() + days);
return toISODate(date);
};
export default function PresetDates() {
const [publishOn, setPublishOn] = useState('');
return (
);
}
```
#### Controlled/Stateful: check-out starts after check-in
The check-in day drives the `min` of the check-out field. When check-in moves past an already typed check-out, the check-out is clamped to the new `min` and `onChangeValue` reports the clamped day, so the night count stays correct.
```tsx
import { useState } from 'react';
import {
CalendarContent,
CalendarDay,
CalendarDays,
CalendarHeader,
CalendarMonth,
CalendarMonthLabel,
CalendarMonths,
CalendarNextButton,
CalendarPrevButton,
CalendarViewButton,
CalendarViewButtonGroup,
CalendarWeekday,
CalendarWeekdays,
CalendarWeeks,
CalendarYear,
CalendarYearLabel,
CalendarYears,
DateField,
DateFieldCalendar,
DateFieldInput,
DateFieldTriggerIconButton,
Fieldset,
FieldsetLegend,
Label,
Popover,
PopoverContent,
PopoverTrigger,
Text,
} from '@vega-ui/react';
const addDays = (iso: string, days: number) => {
const date = new Date(`${iso}T00:00:00Z`);
date.setUTCDate(date.getUTCDate() + days);
return date.toISOString().slice(0, 10);
};
const countNights = (checkIn: string, checkOut: string) => {
return (Date.parse(checkOut) - Date.parse(checkIn)) / 86_400_000;
};
export default function StayDates() {
const [checkIn, setCheckIn] = useState('');
const [checkOut, setCheckOut] = useState('');
const checkOutMin = checkIn ? addDays(checkIn, 1) : undefined;
const nights = checkIn && checkOut ? countNights(checkIn, checkOut) : 0;
return (
);
}
```
### Form/Integration
#### Form/Integration: submitting an ISO date
`DateFieldInput` is a native ``: with a `name` it would submit the typed text, for example `15.01.2026`. Here `onChangeValue` mirrors the ISO day into a hidden input, so `FormData` gets `2026-01-15`. `required` and `pattern` block an empty or incomplete date, and the reset button restores `defaultValue`.
```tsx
import { FormEvent, useState } from 'react';
import {
Button,
CalendarContent,
CalendarDay,
CalendarDays,
CalendarHeader,
CalendarMonth,
CalendarMonthLabel,
CalendarMonths,
CalendarNextButton,
CalendarPrevButton,
CalendarViewButton,
CalendarViewButtonGroup,
CalendarWeekday,
CalendarWeekdays,
CalendarWeeks,
CalendarYear,
CalendarYearLabel,
CalendarYears,
DateField,
DateFieldCalendar,
DateFieldInput,
DateFieldTriggerIconButton,
HelperText,
Label,
Popover,
PopoverContent,
PopoverTrigger,
Text,
} from '@vega-ui/react';
const DEFAULT_INVOICE_DATE = '2026-01-15';
export default function InvoiceForm() {
const [invoiceDate, setInvoiceDate] = useState(DEFAULT_INVOICE_DATE);
const [submitted, setSubmitted] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setSubmitted(JSON.stringify(Object.fromEntries(data)));
};
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: date field inside a dialog
The calendar popover opens above the dialog that contains the field. The form uses `method='dialog'`, so a valid submit closes the dialog.
```tsx
import { CSSProperties } from 'react';
import { XIcon } from '@vega-ui/icons';
import {
Button,
CalendarContent,
CalendarDay,
CalendarDays,
CalendarHeader,
CalendarMonth,
CalendarMonthLabel,
CalendarMonths,
CalendarNextButton,
CalendarPrevButton,
CalendarViewButton,
CalendarViewButtonGroup,
CalendarWeekday,
CalendarWeekdays,
CalendarWeeks,
CalendarYear,
CalendarYearLabel,
CalendarYears,
DateField,
DateFieldCalendar,
DateFieldInput,
DateFieldTriggerIconButton,
Dialog,
DialogClose,
DialogContent,
DialogTrigger,
Heading,
Icon,
IconButton,
Label,
Popover,
PopoverContent,
PopoverTrigger,
} from '@vega-ui/react';
export default function DateFieldInsideADialog() {
return (
);
}
```
#### Layout/Overlay: close the calendar after a pick
The popover stays open after a pick by default, so users can correct it. To close it on pick, control `open` on the `Popover` and close it from `onChangeValue` of `DateFieldCalendar`; navigating months does not call it.
```tsx
import { useState } from 'react';
import {
CalendarContent,
CalendarDay,
CalendarDays,
CalendarHeader,
CalendarMonth,
CalendarMonthLabel,
CalendarMonths,
CalendarNextButton,
CalendarPrevButton,
CalendarViewButton,
CalendarViewButtonGroup,
CalendarWeekday,
CalendarWeekdays,
CalendarWeeks,
CalendarYear,
CalendarYearLabel,
CalendarYears,
DateField,
DateFieldCalendar,
DateFieldInput,
DateFieldTriggerIconButton,
Label,
Popover,
PopoverContent,
PopoverTrigger,
} from '@vega-ui/react';
export default function CloseCalendarAfterPick() {
const [open, setOpen] = useState(false);
return (
setOpen(false)}>
);
}
```
### Error
#### Error: required and incomplete dates
`required` and `pattern` are native constraints of the input: submit fires `invalid` while the field is empty or the date is incomplete. The handler picks the message from `validity`, `error` on the root and `aria-invalid` mark the field, and typing clears the error. The mask clamps every complete date to a real day, so checking completeness is enough.
```tsx
import { FormEvent, useState } from 'react';
import {
Button,
CalendarContent,
CalendarDay,
CalendarDays,
CalendarHeader,
CalendarMonth,
CalendarMonthLabel,
CalendarMonths,
CalendarNextButton,
CalendarPrevButton,
CalendarViewButton,
CalendarViewButtonGroup,
CalendarWeekday,
CalendarWeekdays,
CalendarWeeks,
CalendarYear,
CalendarYearLabel,
CalendarYears,
DateField,
DateFieldCalendar,
DateFieldInput,
DateFieldTriggerIconButton,
HelperText,
Label,
Popover,
PopoverContent,
PopoverTrigger,
} from '@vega-ui/react';
const HINT = 'Enter the full date as dd.mm.yyyy.';
export default function RenewalForm() {
const [error, setError] = useState('');
const invalid = error !== '';
const onInvalid = (event: FormEvent) => {
if (event.currentTarget.validity.valueMissing) {
setError('Enter the renewal date.');
return;
}
setError('The date is incomplete. Use dd.mm.yyyy.');
};
return (
);
}
```
### Disabled
#### Disabled: locked contract date
`disabled` on the root disables the input and the calendar trigger. The helper text explains why the date cannot be changed.
```tsx
import {
CalendarContent,
CalendarDay,
CalendarDays,
CalendarHeader,
CalendarMonth,
CalendarMonthLabel,
CalendarMonths,
CalendarNextButton,
CalendarPrevButton,
CalendarViewButton,
CalendarViewButtonGroup,
CalendarWeekday,
CalendarWeekdays,
CalendarWeeks,
CalendarYear,
CalendarYearLabel,
CalendarYears,
DateField,
DateFieldCalendar,
DateFieldInput,
DateFieldTriggerIconButton,
HelperText,
Label,
Popover,
PopoverContent,
PopoverTrigger,
} from '@vega-ui/react';
export default function LockedContractDate() {
return (
The contract is signed. Create an amendment to change the date.
);
}
```
#### Disabled: disabled by a fieldset
A native `