---
url: "https://vueda.dev/v3/reference/api/vue/WidgetDateField.md"
title: "WidgetDateField"
---

# WidgetDateField

## Overview

A date or datetime picker widget that combines segment-based input with a
calendar popover. Uses DateField for keyboard-friendly segment editing
and Calendar for visual date selection. Set granularity to "minute" or
"second" for datetime input.

Theme entry: [WidgetDateField](/v3/reference/theming/keys/WidgetDateField.md)

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <span id="prop-iconOverride">iconOverride</span> | `Object` |  | `null` | A partial icon registry (`{ [componentName]: { [iconName]: { component, props } } }`) merged with inherited and default icon entries; scopes icon overrides to this component and its descendants. |
| <span id="prop-themeOverride">themeOverride</span> | `Object` |  | `null` | A partial ThemeObject keyed by component name, merged over this component's theme and provided to descendants. |
| <span id="prop-name">name</span> | `String` |  | `undefined` | The widget name; falls back to the field context value when omitted. |
| <span id="prop-label">label</span> | `String` |  | `undefined` | The label displayed next to the widget; falls back to the field context value when omitted. |
| <span id="prop-help">help</span> | `String` |  | `undefined` | Help text displayed alongside the widget; falls back to the field context value when omitted. |
| <span id="prop-readOnly">readOnly</span> | `Boolean` |  | `false` | Whether the widget is read-only; falls back to the field context value when omitted. |
| <span id="prop-required">required</span> | `Boolean` |  | `undefined, // let the default from field context take over` | Whether the widget is required; falls back to the field context value when undefined. |
| <span id="prop-modelValue">modelValue</span> | `String\|Number\|Boolean\|Array\|Object` |  | `undefined` | The widget's bound value (v-model); used only in contextless mode. |
| <span id="prop-fieldToWidget">fieldToWidget</span> | `Object\|Function` |  | `null` | Adapter that converts the form model value into a value suitable for the widget UI. |
| <span id="prop-widgetToField">widgetToField</span> | `Object\|Function` |  | `null` | Adapter that converts the widget UI value back into a form model value for validation and submission. |
| <span id="prop-invalid">invalid</span> | `Boolean` |  | `undefined` | Manually set the invalid state when not in a field context. |
| <span id="prop-warning">warning</span> | `Boolean` |  | `undefined` | Manually set the warning state when not in a field context. |
| <span id="prop-disabled">disabled</span> | `Boolean` |  | `false` | Whether the widget is disabled. |
| <span id="prop-disabledFn">disabledFn</span> | `Function` |  | `null` | A function that returns whether the widget should be disabled; takes precedence over the disabled prop. |
| <span id="prop-contextless">contextless</span> | `Boolean` |  | `false` | When true, the widget ignores any surrounding field or form context and manages its own state. |
| <span id="prop-displayDependencies">displayDependencies</span> | `Array` |  | `() => []` | Field paths whose values the widget needs for display logic; registered with the field context. |
| <span id="prop-granularity">granularity</span> | `string` |  | `"day"` | The granularity of the field: "day" for date-only, "hour"/"minute"/"second" for datetime. |
| <span id="prop-minValue">minValue</span> | `object` |  | `undefined` | The minimum selectable date (@internationalized/date object). |
| <span id="prop-maxValue">maxValue</span> | `object` |  | `undefined` | The maximum selectable date (@internationalized/date object). |
| <span id="prop-locale">locale</span> | `string` |  | `undefined` | The locale used for formatting segment labels. |
| <span id="prop-hideTimeZone">hideTimeZone</span> | `boolean` |  | `undefined` | Whether to hide the time zone segment when using zoned datetime values. |
| <span id="prop-hourCycle">hourCycle</span> | `number` |  | `undefined` | The hour cycle for time formatting (12 or 24). |

## Events

| Name | Description |
| --- | --- |
| `update:modelValue` | Emitted when the widget value changes. |

[Full event reference](/v3/reference/api/vue/WidgetDateField/events.md)

## Source

`client/lib/widgets/WidgetDateField.vue`