---
title: DatePicker
description: >-
The DatePicker component is a calendar picker UI that allows users to select a
single date or a date range
api_version: 2024-10
api_name: checkout-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/checkout-ui-extensions/2024-10/components/forms/datepicker
md: >-
https://shopify.dev/docs/api/checkout-ui-extensions/2024-10/components/forms/datepicker.md
---
# DatePicker
The DatePicker component is a calendar picker UI that allows users to select a single date or a date range
## DatePickerProps
* 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 that is run whenever a date is selected or unselected. 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 that is run whenever the month is changed. 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.
* 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
```
```ts
export interface DateRange {
/** First day (inclusive) of the selected range */
start?: DateString;
/** Last day (inclusive) of the selected range */
end?: 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
```
```ts
export enum Day {
Sunday,
Monday,
Tuesday,
Wednesday,
Thursday,
Friday,
Saturday,
}
```
### Examples
* #### Basic DatePicker
##### React
```tsx
import {
reactExtension,
DatePicker,
} from '@shopify/ui-extensions-react/checkout';
export default reactExtension(
'purchase.checkout.block.render',
() => ,
);
function Extension() {
return ;
}
```
##### JS
```js
import {extension, DatePicker} from '@shopify/ui-extensions/checkout';
export default extension('purchase.checkout.block.render', (root) => {
const datepicker = root.createComponent(DatePicker, {
selected: '2021-06-01',
});
root.appendChild(datepicker);
});
```
## Preview
## Best Practices
By adhering to these design guidelines, the DatePicker component can offer a seamless and efficient method for users to select dates, thereby enhancing the overall user experience.
* Default to showing today’s date if available.
* Display the first available date when selecting future dates.
* To minimize errors, the process of selecting a date range may require multiple steps. Therefore, providing a way for users to explicitly confirm their selection is recommended.
**When to use a DatePicker**
The DatePicker component is well-suited for the following scenarios:
* Specifying shipping or delivery dates
* Scheduling pick-up dates
* Booking dates for service providers
* Selecting event dates for ticket offerings
* Specifying rental dates to determine start and end dates for renting a product
**When not to use a DatePicker component**
A DatePicker component might not be the most appropriate choice in the following situations:
* When the date to be entered is several years in the future or the past.
* When the date is easily memorable and can be quickly typed using the keyboard e.g. Date of birth.