--- title: DatePicker description: >- The `DatePicker` 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 tight spaces, consider using [`DateSpinner`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datespinner) instead. For text date entry, use [`DateField`](/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datefield). api_version: 2025-10 api_name: pos-ui-extensions source_url: html: >- https://shopify.dev/docs/api/pos-ui-extensions/latest/polaris-web-components/forms/datepicker md: >- https://shopify.dev/docs/api/pos-ui-extensions/latest/polaris-web-components/forms/datepicker.md --- # Date​Picker The `DatePicker` 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 tight spaces, consider using [`DateSpinner`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datespinner) instead. For text date entry, use [`DateField`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datefield). Support Targets (16) ### Supported targets * [pos.​cart.​line-item-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/cart-details#cart-details-action-modal-) * [pos.​customer-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/customer-details#customer-details-action-modal-) * [pos.​customer-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/customer-details#customer-details-block-) * [pos.​draft-order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/draft-order-details#draft-order-details-action-modal-) * [pos.​draft-order-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/draft-order-details#draft-order-details-block-) * [pos.​exchange.​post.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-exchange#post-exchange-action-modal-) * [pos.​exchange.​post.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-exchange#post-exchange-block-) * [pos.​home.​modal.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/home-screen#home-screen-action-modal-) * [pos.​order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/order-details#order-details-action-modal-) * [pos.​order-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/order-details#order-details-block-) * [pos.​product-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/product-details#product-details-action-modal-) * [pos.​product-details.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/product-details#product-details-block-) * [pos.​purchase.​post.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-purchase#post-purchase-action-modal-) * [pos.​purchase.​post.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-purchase#post-purchase-block-) * [pos.​return.​post.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-return#post-return-action-modal-) * [pos.​return.​post.​block.​render](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/targets/post-return#post-return-block-) #### Use cases * **Visual selection:** Provide visual date selection for appointments or scheduling workflows. * **Report filtering:** Enable quick date selection for filtering reports or analytics. * **Touch optimization:** Support touch-optimized date input on POS devices. * **Calendar context:** Allow users to see calendar context like day of week when selecting dates. ## Examples ### Select dates with a calendar picker Enable visual date selection using a `DatePicker` component with a calendar interface. This example shows a basic date picker with month view and date selection. ## Select dates with a calendar picker ![](https://shopify.dev/images/templated-apis-screenshots/pos-ui-extensions/2025-10/date-picker-default.png) ### Control picker visibility Control `DatePicker` visibility programmatically using the command system with `show` and `hide` methods. This example demonstrates using button commands to display or dismiss the calendar picker, enabling custom trigger patterns for date selection workflows. ### Handle date selection events Subscribe to date selection events to respond when merchants pick a date from the calendar. This example shows how to handle `onChange` events to capture selected dates, enabling validation, scheduling logic, or dynamic updates based on the chosen date. ### Examples * #### Select dates with a calendar picker ##### Description Enable visual date selection using a \`DatePicker\` component with a calendar interface. This example shows a basic date picker with month view and date selection. ##### Default ```html Show ``` * #### Control picker visibility ##### Description Control \`DatePicker\` visibility programmatically using the command system with \`show\` and \`hide\` methods. This example demonstrates using button commands to display or dismiss the calendar picker, enabling custom trigger patterns for date selection workflows. ##### Default ```jsx <> Select Date console.log('Date selected:', event.currentTarget.value)} /> ; ``` * #### Handle date selection events ##### Description Subscribe to date selection events to respond when merchants pick a date from the calendar. This example shows how to handle \`onChange\` events to capture selected dates, enabling validation, scheduling logic, or dynamic updates based on the chosen date. ##### Default ```jsx console.log('Input:', event.currentTarget.value)} onChange={(event) => console.log('Change:', event.currentTarget.value)} onFocus={(event) => console.log('Focus')} onBlur={(event) => console.log('Blur')} /> ``` ## Properties Configure the following properties on the `DatePicker` component. * id string A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features. * value string Default: "" The currently selected date value in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DD`, for example, `"2024-05-15"`). An empty string means no date is selected. Other date formats require conversion before setting this property. Validation occurs when the user finishes editing (on blur), rather than on every keystroke, so invalid dates are flagged after completing entry. ## Events The `DatePicker` 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 (event: CallbackEvent<"s-date-picker">) => void Called when the element loses focus. * change (event: CallbackEvent<"s-date-picker">) => void Called after editing completes, typically on blur. * focus (event: CallbackEvent<"s-date-picker">) => void Called when the element receives focus. * input (event: CallbackEvent<"s-date-picker">) => void Called when the user makes any changes in the field. ### CallbackEvent Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior. * bubbles Whether the event bubbles up through the DOM tree. ```ts boolean ``` * cancelable Whether the event can be canceled. ```ts boolean ``` * composed Whether the event will trigger listeners outside of a shadow root. ```ts boolean ``` * currentTarget The element that the event listener is attached to. ```ts HTMLElementTagNameMap[T] ``` * detail Additional data associated with the event. ```ts any ``` * eventPhase The current phase of the event flow. ```ts number ``` * target The element that triggered the event. ```ts HTMLElementTagNameMap[T] | null ``` ```ts interface CallbackEvent { /** * The element that the event listener is attached to. */ currentTarget: HTMLElementTagNameMap[T]; /** * Whether the event bubbles up through the DOM tree. */ bubbles?: boolean; /** * Whether the event can be canceled. */ cancelable?: boolean; /** * Whether the event will trigger listeners outside of a shadow root. */ composed?: boolean; /** * Additional data associated with the event. */ detail?: any; /** * The current phase of the event flow. */ eventPhase: number; /** * The element that triggered the event. */ target: HTMLElementTagNameMap[T] | null; } ``` ## Best practices * **Choose for calendar-based selection:** Use `DatePicker` when users benefit from seeing a calendar view, like selecting dates relative to today or needing weekday context. Use [`DateSpinner`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datespinner) for tight spaces or [`DateField`](https://shopify.dev/docs/api/pos-ui-extensions/2025-10/polaris-web-components/forms/datefield) when users know the exact date. * **Provide adequate space:** Ensure sufficient spacing around the picker to avoid interfering with on-screen keyboards or other interactive elements.