--- 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. The component supports single dates, multiple dates, and date ranges. For text date entry, use [date field](/docs/api/checkout-ui-extensions/2026-04/web-components/forms/date-field). 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. For text date entry, use [date field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/date-field). ### Support Targets (29) ### Supported targets * purchase.​checkout.​actions.​render-before * purchase.​checkout.​block.​render * purchase.​checkout.​cart-line-item.​render-after * purchase.​checkout.​cart-line-list.​render-after * purchase.​checkout.​contact.​render-after * purchase.​checkout.​delivery-address.​render-after * purchase.​checkout.​delivery-address.​render-before * purchase.​checkout.​footer.​render-after * purchase.​checkout.​header.​render-after * purchase.​checkout.​payment-method-list.​render-after * purchase.​checkout.​payment-method-list.​render-before * purchase.​checkout.​pickup-location-list.​render-after * purchase.​checkout.​pickup-location-list.​render-before * purchase.​checkout.​pickup-location-option-item.​render-after * purchase.​checkout.​pickup-point-list.​render-after * purchase.​checkout.​pickup-point-list.​render-before * purchase.​checkout.​reductions.​render-after * purchase.​checkout.​reductions.​render-before * purchase.​checkout.​shipping-option-item.​details.​render * purchase.​checkout.​shipping-option-item.​render-after * purchase.​checkout.​shipping-option-list.​render-after * purchase.​checkout.​shipping-option-list.​render-before * purchase.​thank-you.​announcement.​render * purchase.​thank-you.​block.​render * purchase.​thank-you.​cart-line-item.​render-after * purchase.​thank-you.​cart-line-list.​render-after * purchase.​thank-you.​customer-information.​render-after * purchase.​thank-you.​footer.​render-after * purchase.​thank-you.​header.​render-after ## Properties * **allow** **string** **Default: ""** Dates that can be selected. A comma-separated list of dates, 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 `--`. * **allowDays** **string** **Default: ""** Days of the week that can be selected. These intersect with the result of `allow` and `disallow`. 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 `--`. * **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. * **view** **string** Displayed month in `YYYY-MM` format. `onViewChange` is called when this value changes. Defaults to `defaultView`. ## Events Learn more about [registering events](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/using-polaris-components#event-handling). * **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 ## Preview ![](https://cdn.shopify.com/shopifycloud/shopify-dev/development/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/date-picker-default-BAGGp2Ed.png) ### Examples * #### Code ##### Default ```html ```