---
title: DatePicker
description: Allow users to select a specific date or date range.
api_version: 2026-01
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-web-components/forms/datepicker
  md: https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-web-components/forms/datepicker.md
---

# Date​Picker

Allow users to select a specific date or date range.

## 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**

  Disables the field, disallowing any 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.

* **name**

  **string**

  An identifier for the field that is 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-01/using-polaris-components#event-handling).

* **blur**

  **CallbackEventListener\<typeof tagName>**

  Callback when the element loses focus.

* **change**

  **CallbackEventListener\<typeof tagName>**

  Callback when the user has **finished editing** a field, e.g. once they have blurred the field.

* **focus**

  **CallbackEventListener\<typeof tagName>**

  Callback when the element receives focus.

* **input**

  **CallbackEventListener\<typeof tagName>**

  Callback when the user makes any changes in the field.

* **viewChange**

  **CallbackEventListener\<typeof tagName>**

  Callback when the view changes.

### CallbackEventListener

```ts
(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): void;
}) | null
```

### CallbackEvent

```ts
TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}
```

Examples

## Preview

![](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/date-picker-default-DALRzOEj.png)

### Examples

* #### Code

  ##### Default

  ```html
  <s-date-picker defaultView="2025-10" defaultValue="2025-10-03"></s-date-picker>
  ```