--- title: DateField description: The date field component captures date input for scheduling or data entry. api_version: 2025-07 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/datefield md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/datefield.md --- Migrate to Polaris Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension. # DateField The date field component captures date input with a consistent interface for date selection and proper validation. Use it to collect date information in forms, scheduling interfaces, or data entry workflows. The component supports manual text entry. For visual calendar-based selection, consider using [DatePicker](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/datepicker). ### Support Targets (25) ### Supported targets * Customer​Account::Kitchen​Sink * [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-) * [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets) * [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-) * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-) * [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-) * [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets) * [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-) * [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-) * [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-) * [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-) * [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-) * [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-) * [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-) * [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-) * [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-) * [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-) * [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-) * customer-account.​profile.​payment.​render-after #### Use cases * **Delivery scheduling**: Let customers type a preferred delivery or pickup date. * **Date restrictions**: Set minimum and maximum dates to constrain valid input. * **Pre-filled dates**: Display a saved date that customers can update. * **Read-only display**: Show a date value that customers can't edit. *** ## Properties Configure the following properties on the DateField component. * **label** **string** **required** The text displayed as the field label, which identifies the purpose of the field to users. This value is also used as the placeholder when the field is empty. * **defaultYearMonth** **YearMonth** Default [uncontrolled](https://reactjs.org/docs/forms.html#controlled-components) year and month to display. Ignored when year/month navigation is controlled. * **disabled** **DisabledDate\[] | boolean** Disabled dates, days, and/or ranges, or the date picker. Unbound range disables all dates either from `start` date or to `end` date. `true` disables the date picker. * **error** **string** An error message displayed below the field to indicate validation problems. When set, the field is styled with error indicators. * **id** **string** A unique identifier for the field. When no `id` is set, a globally unique value will be used instead. * **name** **string** An identifier for the field that is unique within the nearest containing `Form` component. * **onBlur** **() => void** A callback fired when the text field loses focus. * **onChange** **(value: string) => void** A callback fired when the user has **finished editing** the field, such as when they blur the field. Unlike `onChange` callbacks you may be familiar with from Polaris or other React component libraries, this callback is **not** run on every change to the input. Text fields are “partially controlled” components, which means that while the user edits the field, its state is controlled by the component. Once the user has signalled that they have finished editing the field (typically, by blurring the field), `onChange` is called if the input actually changed from the most recent `value` property. At that point, you are expected to store this “committed value” in state, and reflect it in the text field’s `value` property. This state management model is important given how UI Extensions are rendered. UI Extension components run on a separate thread from the UI, so they can’t respond to input synchronously. A pattern popularized by [controlled React components](https://reactjs.org/docs/forms.html#controlled-components) is to have the component be the source of truth for the input `value`, and update the `value` on every user input. The delay in responding to events from a UI extension is only a few milliseconds, but attempting to strictly store state with this delay can cause issues if a user types quickly, or if the user is using a lower-powered device. Having the UI thread take ownership for “in progress” input, and only synchronizing when the user is finished with a field, avoids this risk. It can still sometimes be useful to be notified when the user makes any input in the field. If you need this capability, you can use the `onInput` prop. However, never use that property to create tightly controlled state for the `value`. This callback is called with the current value of the field. If the value of a field is the same as the current `value` prop provided to the field, the `onChange` callback will not be run. * **onFocus** **() => void** A callback fired when the text field receives focus. * **onInput** **(value: string) => void** A callback fired when the user makes any changes in the field, such as typing a character. As noted in the documentation for `onChange`, you must not use this to update `state` — use the `onChange` callback for that purpose. Use the `onInput` prop when you need to do something as soon as the user makes a change, like clearing validation errors that apply to the field as soon as the user begins making the necessary adjustments. This callback is called with the current value of the field. * **onInvalid** **() => void** A callback fired when the date field contains an invalid or disabled date after the user finishes editing. This callback is invoked when the date typed is invalid or disabled. Dates that don’t exist or have formatting errors are considered invalid. Some examples of invalid dates are: * 2021-02-31: February doesn’t have 31 days * 2021-02-00: The day can’t be 00 Dates and ranges specified in the `disabled` property are considered disabled dates. If the `disabled` property is `2021-06-14`, and the user types `2021-06-14`, this callback will be called as this date is disabled. Note that this will be called only when the user **finishes editing** the date, after the `onChange` callback. The field is **not** validated on every change to the input. Once the user has signalled that they have finished editing the field (typically, by blurring the field), the field gets validated and the callback is run if the value is invalid. * **onYearMonthChange** **(yearMonth: { year: number; month: number; }) => void** A callback fired when the displayed year and month change. This callback is called with an object indicating the year/month the UI should change to. When year/month navigation is controlled you must store these values in state and reflect it back in the `yearMonth` prop. * **readonly** **boolean** Whether the field is read-only and can't be edited. Read-only fields remain focusable and their content is announced by screen readers. * **value** **T** The current value for the field. If omitted, the field will be empty. You should update this value in response to the `onChange` callback. * **yearMonth** **YearMonth** [Controlled](https://reactjs.org/docs/forms.html#controlled-components) year and month to display. Use in combination with `onYearMonthChange`. Makes year/month navigation controlled. ### YearMonth ```ts {year: number; month: number} | YearMonthString ``` ### YearMonthString A year/month string using the simplified ISO 8601 format (\`YYYY-MM\`) ```ts string ``` ### DisabledDate ```ts DateString | DateRange | DayString ``` ### DateString ```ts string ``` ### DateRange * end Last day (inclusive) of the selected range ```ts DateString ``` * start First day (inclusive) of the selected range ```ts DateString ``` ### DayString ```ts keyof typeof Day ``` ### Day * Sunday ```ts 0 ``` * Monday ```ts 1 ``` * Tuesday ```ts 2 ``` * Wednesday ```ts 3 ``` * Thursday ```ts 4 ``` * Friday ```ts 5 ``` * Saturday ```ts 6 ``` *** ## Examples ### Enter a date Use date field to collect a typed date value from customers. This example shows a basic labeled date input. ## Enter a date ![A date field with labeled input for entering a date](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/datefield-default-CgY-8doG.png) ## Enter a date ##### React ```tsx import { reactExtension, DateField, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ; } ``` ##### JS ```js import {extension, DateField} from '@shopify/ui-extensions/customer-account'; export default extension('customer-account.page.render', (root) => { const datefield = root.createComponent(DateField, { label: 'Select a date', }); root.appendChild(datefield); }); ``` *** ## Best practices * **Set meaningful defaults**: Use `defaultValue` to pre-fill the next available date and reduce manual input. * **Restrict invalid dates**: Use `disallow` and `disallowDays` to prevent customers from selecting dates that aren't available for fulfillment. * **Pair with date picker**: For date selection that benefits from calendar context, use [DatePicker](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/datepicker) alongside or instead of a date field. *** ## Limitations * Date values must use YYYY-MM-DD format. ***