---
title: Migrate to the Polaris date picker component
description: >-
  Learn how to migrate the DatePicker component to Polaris web components in
  checkout and customer account UI extensions.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/date-picker
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/date-picker.md
---

# Migrate to the Polaris date picker component

The Polaris date picker component displays a calendar for selecting dates, date ranges, or multiple dates. It replaces the previous [`DatePicker`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/forms/datepicker) component and is available as [`<s-date-picker>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris date picker component.

### selected

The previous `DatePicker` `selected` prop has been split into [`type`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-type) and either [`defaultValue`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-defaultvalue) (uncontrolled) or [`value`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-value) (controlled).

If you were using `selected` with state and `onChange` to control the picker, use `value` instead of `defaultValue` to keep the component controlled.

| Previous pattern | New pattern (uncontrolled) | New pattern (controlled) |
| - | - | - |
| `selected="2024-12-25"` | `type="single"` + `defaultValue="2024-12-25"` | `type="single"` + `value="2024-12-25"` |
| `selected={['2024-12-24', '2024-12-25']}` | `type="multiple"` + `defaultValue="2024-12-24,2024-12-25"` | `type="multiple"` + `value="2024-12-24,2024-12-25"` |
| `selected={{start: '2024-12-24', end: '2024-12-31'}}` | `type="range"` + `defaultValue="2024-12-24--2024-12-31"` | `type="range"` + `value="2024-12-24--2024-12-31"` |

## Migrating selected (controlled)

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  const [range, setRange] = useState('2024-12-24--2024-12-31');

  return (
    <s-date-picker
      type="range"
      value={range}
      onChange={(event) => setRange(event.currentTarget.value)}
    />
  );
}
```

##### Pre-Polaris (2025-07)

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

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

function Extension() {
  const [range, setRange] = useState({
    start: '2024-12-24',
    end: '2024-12-31',
  });

  return (
    <DatePicker
      selected={range}
      onChange={(newRange) => setRange(newRange)}
    />
  );
}
```

### year​Month

The previous `DatePicker` `yearMonth` prop is now called [`view`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-view). It takes a `YYYY-MM` string instead of a `{year, month}` object.

### default​Year​Month

The previous `DatePicker` `defaultYearMonth` prop is now called [`defaultView`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-defaultview). It takes a `YYYY-MM` string.

### disabled

The previous `disabled` prop behavior has changed. Setting `disabled` to `true` still disables the entire picker. For disabling specific dates or days, use the new [`disallow`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-disallow) and [`disallowDays`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-disallowdays) props.

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `disabled={true}` | `disabled` | No change needed. |
| `disabled={['2024-12-25', '2024-12-26']}` | `disallow="2024-12-25,2024-12-26"` | Specific dates use comma-separated string in `disallow`. |
| `disabled={['Sunday', 'Saturday']}` | `disallowDays="sunday,saturday"` | Days of week use `disallowDays`. |
| `disabled={[{start: '2024-12-01', end: '2024-12-10'}]}` | `disallow="2024-12-01--2024-12-10"` | Date ranges use double-dash separator. |

## Migrating disabled dates

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-date-picker
      type="single"
      defaultValue="2024-12-15"
      disallow="2024-12-25,2024-12-26"
      disallowDays="saturday,sunday"
    />
  );
}
```

##### Pre-Polaris (2025-07)

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

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

function Extension() {
  return (
    <DatePicker
      selected="2024-12-15"
      disabled={[
        '2024-12-25',
        '2024-12-26',
        'Saturday',
        'Sunday',
      ]}
    />
  );
}
```

### on​Change

The previous `onChange` prop is still available as [`onChange`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#events-propertydetail-change). It fires when the user finishes editing — for `type="range"`, this means after the end date is selected. The Polaris date picker also introduces [`onInput`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#events-propertydetail-input), which fires on every individual date selection. Use `onChange` for committed values and `onInput` when you need to react to each selection.

### on​Year​Month​Change

The previous `onYearMonthChange` prop is now called [`onViewChange`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#events-propertydetail-viewchange).

***

## Removed properties

### read​Only

The Polaris date picker component no longer supports `readOnly`. Use `disabled` instead.

***

## New properties

The Polaris date picker component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`type`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-type) | `'single'` \| `'multiple'` \| `'range'` | Selection mode. Default: `'single'`. |
| [`allow`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-allow) | `string` | Comma-separated list of allowed dates. |
| [`allowDays`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-allowdays) | `string` | Comma-separated list of allowed days. |
| [`disallow`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-disallow) | `string` | Comma-separated list of disallowed dates. |
| [`disallowDays`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/date-picker#properties-propertydetail-disallowdays) | `string` | Comma-separated list of disallowed days. |

***