---
title: DatePicker
description: >-
The date picker component lets customers select dates using a visual calendar
interface.
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/datepicker
md: >-
https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/datepicker.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.
# DatePicker
The date picker component lets customers select dates using a visual calendar interface. Use it when customers benefit from seeing dates in context of the full month, such as selecting dates relative to today or needing weekday context.
The component supports single dates, multiple dates, and date ranges. For text date entry, use [DateField](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/datefield).
### Support Targets (25)
### Supported targets
* CustomerAccount::KitchenSink
* [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 pick a delivery or pickup date from a calendar.
* **Date range selection**: Allow customers to select a start and end date visually.
* **Restricted calendars**: Disable unavailable dates to prevent invalid selections.
* **Pre-selected dates**: Default to today's date or the next available date.
***
## Properties
Configure the following properties on the DatePicker component.
* **selected**
**T**
**required**
A date, an array of dates, or a range object with `start` and/or `end` keys indicating the selected dates. When a range is set, dates between the boundaries will be selected.
* **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.
* **onChange**
**(selected: T) => void**
A callback fired when the selected date or dates change. This callback is called with a string, an array of strings or a range object representing the selected dates. This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components), so you must store these values in state and reflect it back in the `selected` props.
* **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 date picker is read-only and can't be edited. Read-only date pickers remain focusable and their state is announced by screen readers where applicable.
* **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
### Select a date from a calendar
Use date picker to display a visual calendar that customers can browse and select dates from. This example shows a basic calendar view with selectable dates.
## Select a date from a calendar
## Select a date from a calendar
##### React
```tsx
import {
reactExtension,
DatePicker,
} from '@shopify/ui-extensions-react/customer-account';
export default reactExtension(
'customer-account.page.render',
() => ,
);
function Extension() {
return ;
}
```
##### JS
```js
import {extension, DatePicker} from '@shopify/ui-extensions/customer-account';
export default extension('customer-account.page.render', (root) => {
const datepicker = root.createComponent(DatePicker, {
selected: '2021-06-01',
});
root.appendChild(datepicker);
});
```
***
## Best practices
* **Set a default view**: Use `defaultView` to open the calendar to the most relevant month, such as the current or next month.
* **Restrict invalid dates**: Use `disallow` with date ranges and `disallowDays` with day names to prevent customers from selecting unavailable dates.
* **Choose the right selection mode**: Use `type="range"` for booking windows and the default single mode for one-off date selections.
***
## Limitations
* Time selection isn't available.
***