DateField

DateField is a compound component for single-date entry that combines typed input, optional calendar selection, and field-level constraints in one control.

Storybook Source

Root Props

Prop	Type	Default
`value`	`string`	—
Controlled date as a `YYYY-MM-DD` string, `''` while the field has no complete date.
`defaultValue`	`string`	`''`
Initial date for uncontrolled usage as a `YYYY-MM-DD` string. Defaults to `''`, an empty field.
`onChangeValue`	`(value: string) => void`	—
Called with the `YYYY-MM-DD` date when it changes, `''` when the text is emptied or incomplete.
`format`required	`string`	—
Date format pattern used for input masking and parsing. Defines the order of date segments. Examples: "dd.MM.yyyy"; "MM/dd/yyyy"; "yyyy-MM-dd"
`separator`required	`string`	—
Character used to separate date segments in the input. Examples: "."; "/"; "-"
`min`	`string`	—
Minimum allowed date as a `YYYY-MM-DD` string. Dates earlier than this value cannot be selected and will be clamped or rejected during input parsing.
`max`	`string`	—
Maximum allowed date as a `YYYY-MM-DD` string. Dates later than this value cannot be selected and will be clamped or rejected during input parsing.
`disabledDates`	`CalendarDatesDisabled`	—
Rules for disabling specific dates in the calendar. Can be used to block ranges, weekdays, or custom conditions.
`disabled`	`boolean`	—
Disables the field. Prevents user input and interaction and applies the disabled visual state.
`calendar`	`CalendarSystem`	`gregorianCalendar`
Calendar system the date is typed and picked in. The value stays a `YYYY-MM-DD` day. Defaults to the Gregorian calendar.
`locale`	`string`	—
BCP 47 locale of the calendar popup (month and day names, first day of the week), e.g. `de-DE`. The typed format still comes from `format`. Defaults to the locale of the runtime, like `Intl`.
`size`	`TextFieldSize`	—
Visual size of the text field. Affects padding, font size, and overall height. 'sm': Compact input; 'md': Default; 'lg': Spacious layout
`ref`	`Ref<HTMLDivElement>`	—
Ref forwarded to wrapper element Useful for programmatic control, focus, or integration.
`error`	`boolean`	—
Shows the input in an error state.

Also accepts all <div> attributes.

Child Parts

DateFieldInput: typed entry surface.
DateFieldTriggerIconButton: optional calendar trigger button.
DateFieldCalendar: calendar content that stays synchronized with the field value.

`DateFieldInput`

Prop	Type	Default
`ref`	`Ref<HTMLInputElement>`	—
Ref forwarded to the underlying native `<input>` element.

Also accepts all <input> attributes.

`DateFieldCalendar`

Prop	Type	Default
`max`	`string`	—
Latest selectable date as a `YYYY-MM-DD` string. Months and years beyond this date become unavailable. Day, Month, and Year pickers use this to disable or clamp navigation.
`min`	`string`	—
Earliest selectable date as a `YYYY-MM-DD` string. Months and years before this date become unavailable. All pickers respect this constraint when computing active ranges.
`selection`	`"single"`	—
Selection mode. Determines the structure of `value`, all dates are `YYYY-MM-DD` strings: 'single' — a string, `''` when nothing is selected; 'multiple' — an array of strings; 'range' — a `[start, end]` tuple with `start` not after `end`, `''` marks an unset bound. Default: `'single'`
`view`	`CalendarView`	—
Controlled visible view: 'day' — the days of the visible month (`CalendarDays`); 'month' — the months of the visible year (`CalendarMonths`); 'year' — pages of years (`CalendarYears`)
`value`	`string`	—
Controlled selection value, shaped by the `selection` mode. Malformed or non-existent dates are treated as unselected.
`defaultValue`	`string`	—
Uncontrolled initial selection value, shaped by the `selection` mode.
`defaultView`	`CalendarView`	—
Initial view for uncontrolled usage. Default: `'day'`
`disabled`	`boolean`	—
Disables the whole calendar: no date can be selected and navigation is off.
`disabledDates`	`CalendarDatesDisabled`	—
Dates that cannot be selected, as `YYYY-MM-DD` strings: a single date; an array of dates; a predicate `(date: string) => boolean`
`onChangeValue`	`(value: CalendarValue<S>) => void`	—
Fires when the user changes the selection. The value is shaped by the `selection` mode.
`onChangeView`	`(view: CalendarView) => void`	—
Fires when the visible view changes.
`month`	`string`	—
Controlled visible month, given as a `YYYY-MM-DD` string of any day in that month.
`defaultMonth`	`string`	—
Initial visible month for uncontrolled usage, given as a `YYYY-MM-DD` string of any day in that month. Default: the month of the selected date, otherwise the current month
`onChangeMonth`	`(month: string) => void`	—
Fires with the first day of the visible month as a `YYYY-MM-DD` string when the visible month changes (e.g., via scrolling or the month and year pickers). This event represents view navigation, not selection.
`calendar`	`CalendarSystem`	—
Calendar system the calendar is shown in. Values stay `YYYY-MM-DD` days. Defaults to the Gregorian calendar.
`locale`	`string`	—
BCP 47 locale of month and day names and of the first day of the week, e.g. `de-DE`. Applies to all parts of the calendar and sets `lang` on the root. Defaults to the locale of the runtime, like `Intl`.
`size`	`CalendarBaseSize`	—
Global size scale for the calendar. Affects nested controls such as navigation buttons, picker triggers, and week labels via `CalendarBaseContext`.
`variant`	`CalendarBaseVariant`	—
Visual variant for the calendar. Propagated through `CalendarBaseContext` and used by nested controls (buttons, labels, etc.) to keep styling consistent.
`compact`	`boolean`	—
Density flag for more compact layouts. When `true`, the root element receives `data-compact="true"`, allowing styles to reduce paddings, gaps, and control heights for a denser calendar presentation. When `false` or `undefined`, the calendar uses the default spacing.

Also accepts all <div> attributes.

`DateFieldTriggerIconButton`

Prop	Type	Default
`size`	`IconButtonSize`	—
Size of the button container. Controls padding and overall clickable area.
`asChild`	`boolean`	—
When true, renders the button as a child component using `Slot` (e.g., from Radix UI). Enables polymorphic rendering — useful for making the button act as a link or custom tag.
`variant`	`ButtonBaseVariant`	—
Defines the visual style of the button, affecting color schemes and emphasis.
`appearance`	`ButtonBaseAppearance`	—
Adjusts the button's structural appearance (background, border, etc.).
`disabled`	`boolean`	—
Disables the button when true. Prevents user interaction and applies a visually disabled state. Not applied with `asChild`: the child element owns its disabled state, for example, `aria-disabled` or a link without `href`.
`className`	`string`	—
Optional custom CSS class for the button element. Useful for design system overrides or scoped styles.
`children`	`ReactNode`	—
Content of the button — text, icon, or any React node.
`ref`	`Ref<HTMLButtonElement>`	—
Ref forwarded to the native `<button>` element. Allows direct DOM access for focus management or measuring.

Also accepts all <button> attributes.

Types

DateFieldProps
DateFieldInputProps
DateFieldTriggerIconButtonProps
DateFieldCalendarProps

State Model

The root owns the shared date value used by both typed input and calendar selection.
The root takes value, defaultValue and onChangeValue as a YYYY-MM-DD day, like the value of a native <input type="date">; DateFieldInput shows it in format and still fires its own onChange and onInput. While the text is empty or incomplete the value is '' and the calendar shows no selection. A form reset restores defaultValue unless the field is controlled.
When min or max change, typed text is clamped again like typing does, firing input.
Parsing and formatting are driven by format and separator.
min, max, and disabledDates should match product validation, not just visual affordances.
Native form semantics come from the underlying text input, not from a separate hidden select-like part.