--- title: Date picker description: >- The date picker component allows merchants to select dates using a calendar interface. Use it when merchants benefit from seeing dates in context of the full month, such as selecting dates relative to today or needing weekday context. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker.md --- # Date picker The date picker component allows merchants to select dates using a calendar interface. Use it when merchants 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. Time selection isn't supported. For text date entry, use [date field](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-field). ### Support Targets (29) ### Supported targets * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-) * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-) * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target) #### Use cases * **Delivery scheduling:** Let buyers pick a delivery date from a visual calendar that shows the full month. * **Date range selection:** Allow buyers to select a start and end date for subscriptions, rentals, or booking windows. * **Restricted calendars:** Gray out unavailable days like weekends or holidays to guide buyers toward valid dates. * **Pre-selected dates:** Highlight a default date on the calendar to speed up selection for common choices. *** ## Properties Configure the following properties on the date picker component. * **allow** **string** **Default: ""** Restricts which dates the user can select. Accepts a comma-separated list of dates and date ranges. Whitespace is allowed after commas. The default `''` allows all dates. * Dates in `YYYY-MM-DD` format allow a single date. * Dates in `YYYY-MM` format allow a whole month. * Dates in `YYYY` format allow a whole year. * Ranges are expressed as `start--end`. - Ranges are inclusive. * If either `start` or `end` is omitted, the range is unbounded in that direction. * If parts of the date are omitted for `start`, they are assumed to be the minimum possible value. So `2024--` is equivalent to `2024-01-01--`. * If parts of the date are omitted for `end`, they are assumed to be the maximum possible value. So `--2024` is equivalent to `--2024-12-31`. * Whitespace is allowed either side of `--`. Comma-separated list of allowed dates in `YYYY-MM-DD` format. * **allowDays** **string** **Default: ""** Restricts which days of the week the user can select. Only dates that fall on an allowed day AND pass the `allow`/`disallow` filters are selectable. For example, setting `allowedDays` to `'mon, wed, fri'` with `allow` set to `'2024-06'` restricts selection to Mondays, Wednesdays, and Fridays in June 2024. A comma-separated list of days. Whitespace is allowed after commas. The default `''` has no effect on the result of `allow` and `disallow`. Days are `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`. * **defaultValue** **string** **Default: ""** Default selected value. The default means no date is selected. If the provided value is invalid, no date is selected. * If `type="single"`, this is a date in `YYYY-MM-DD` format. * If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format. * If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive. * **defaultView** **string** Default month to display in `YYYY-MM` format. This value is used until `view` is set, either directly or as a result of user interaction. Defaults to the current month in the user's locale. * **disabled** **boolean** **Default: false** Whether the field is disabled, preventing any user interaction. * **disallow** **string** **Default: ""** Dates that cannot be selected. These subtract from `allow`. A comma-separated list of dates, date ranges. Whitespace is allowed after commas. The default `''` has no effect on `allow`. * Dates in `YYYY-MM-DD` format disallow a single date. * Dates in `YYYY-MM` format disallow a whole month. * Dates in `YYYY` format disallow a whole year. * Ranges are expressed as `start--end`. - Ranges are inclusive. * If either `start` or `end` is omitted, the range is unbounded in that direction. * If parts of the date are omitted for `start`, they are assumed to be the minimum possible value. So `2024--` is equivalent to `2024-01-01--`. * If parts of the date are omitted for `end`, they are assumed to be the maximum possible value. So `--2024` is equivalent to `--2024-12-31`. * Whitespace is allowed either side of `--`. Comma-separated list of disallowed dates in `YYYY-MM-DD` format. * **disallowDays** **string** **Default: ""** Days of the week that cannot be selected. This subtracts from `allowDays`, and intersects with the result of `allow` and `disallow`. A comma-separated list of days. Whitespace is allowed after commas. The default `''` has no effect on `allowDays`. Days are `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`. * **id** **string** A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting. * **name** **string** The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form. * **type** **'single' | 'multiple' | 'range'** **Default: "single"** The type of selection the date picker allows. * `single` allows selecting a single date. * `multiple` allows selecting multiple non-contiguous dates. * `range` allows selecting a single range of dates. * **value** **string** **Default: ""** Current selected value. The default means no date is selected. If the provided value is invalid, no date is selected. Otherwise: * If `type="single"`, this is a date in `YYYY-MM-DD` format. * If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format. * If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive. Single dates use ISO 8601 format (`YYYY-MM-DD`); ranges use `YYYY-MM-DD--YYYY-MM-DD`. Locale-specific formats aren't supported. * **view** **string** Displayed month in `YYYY-MM` format. `onViewChange` is called when this value changes. Defaults to `defaultView`. ### Events The date picker component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events). * **blur** **CallbackEventListener\** A callback fired when the date picker loses focus. Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event). * **change** **CallbackEventListener\** A callback fired when the date picker value changes. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event). * **focus** **CallbackEventListener\** A callback fired when the date picker receives focus. Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event). * **input** **CallbackEventListener\** A callback fired when the user inputs data into the date picker. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event). * **viewChange** **CallbackEventListener\** A callback fired when the calendar view changes, such as when navigating between months. ### CallbackEventListener A typed event listener for custom element events. The listener receives a \`CallbackEvent\` with the correct \`currentTarget\` type for the associated custom element tag. ```ts (EventListener & { (event: CallbackEvent & TData): void; }) | null ``` ### CallbackEvent An event type that narrows the \`currentTarget\` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners. ```ts TEvent & { currentTarget: HTMLElementTagNameMap[TTagName]; } ``` *** ## Examples ### Select a date from a calendar Display a visual calendar for date selection with a pre-selected date. This example configures an `s-date-picker` with `defaultView` set to a month and `defaultValue` highlighting a specific day. ## Select a date from a calendar ![A rendered example of the date-picker component](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/date-picker-default-BAGGp2Ed.png) ## html ```html ``` ### Restrict selectable calendar dates Block dates before a cutoff and exclude Sundays from the calendar. This example shows an `s-date-picker` with `disallow` set to dates before December 1, 2026 and `disallowDays` excluding Sundays. ## html ```html ``` ### Select a date range Allow buyers to pick a start and end date for a booking or subscription window. This example uses an `s-date-picker` with `type` set to `range`. ## html ```html ``` *** ## 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 buyers 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. ***