Skip to main content
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.

DatePicker

The DatePicker component is a calendar picker UI that allows users to select a single date or a date range.

Support
Targets (50)

Supported targets

Anchor to DatePickerPropsDatePickerProps

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.

Anchor to ExamplesExamples

Anchor to Basic DatePickerBasic DatePicker

Basic DatePicker

Example

Basic DatePicker

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

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return <DatePicker selected="2021-06-01" />;
}
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);
});

Anchor to Best practicesBest practices

  • Set the initial calendar month: Use defaultYearMonth so the calendar opens on a relevant month, or control yearMonth when navigation is fully controlled.
  • Restrict invalid dates: Use disabled to block specific dates, ranges, or days.
  • Model selection correctly: selected can be a single date string, an array for multiple selection, or a range object with start and/or end, depending on your use case.

Anchor to LimitationsLimitations

  • Time-of-day selection isn't available; only calendar dates are supported.
  • Dates use YYYY-MM-DD strings (range objects use those strings). Locale-specific formats aren't supported.
Was this page helpful?