Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

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.

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the DatePicker component.

Anchor to selected 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.
Anchor to defaultYearMonth defaultYearMonth: Default uncontrolled year and month to display. Ignored when year/month navigation is controlled.
Anchor to disabled disabled [] | 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.
Anchor to onChange 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, so you must store these values in state and reflect it back in the selected props.
Anchor to onYearMonthChange 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.
Anchor to readOnly 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.
Anchor to yearMonth yearMonth: Controlled year and month to display. Use in combination with onYearMonthChange. Makes year/month navigation controlled.

YearMonth

{year: number; month: number} | YearMonthString

YearMonthString

A year/month string using the simplified ISO 8601 format (`YYYY-MM`)

string

DisabledDate

DateString | DateRange | DayString

DateString

string

DateRange

end
Last day (inclusive) of the selected range
```
DateString
```
start
First day (inclusive) of the selected range
```
DateString
```

DayString

keyof typeof Day

Day

Sunday
```
0
```
Monday
```
1
```
Tuesday
```
2
```
Wednesday
```
3
```
Thursday
```
4
```
Friday
```
5
```
Saturday
```
6
```

Anchor to ExamplesExamples

Anchor to Select a date from a calendarSelect 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

A calendar date picker showing the current month with selectable dates

Select a date from a calendar

import {

reactExtension,

DatePicker,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return <DatePicker selected="2021-06-01" />;

}

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);

});

React

import {
  reactExtension,
  DatePicker,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return <DatePicker selected="2021-06-01" />;
}

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);
});

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

Time selection isn't available.

Was this page helpful?