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 component and is available as <s-date-picker> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

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

Anchor to selectedselected

The previous DatePicker selected prop has been split into type and either defaultValue (uncontrolled) or 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.

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)}
    />
  );
}

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)}
    />
  );
}

Anchor to yearMonthyearMonth

The previous DatePicker yearMonth prop is now called view. It takes a YYYY-MM string instead of a {year, month} object.

Anchor to defaultYearMonthdefaultYearMonth

The previous DatePicker defaultYearMonth prop is now called defaultView. It takes a YYYY-MM string.

Anchor to disableddisabled

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 and disallowDays props.

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"
    />
  );
}

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',
      ]}
    />
  );
}

Anchor to onChangeonChange

The previous onChange prop is still available as onChange. 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, which fires on every individual date selection. Use onChange for committed values and onInput when you need to react to each selection.

Anchor to onYearMonthChangeonYearMonthChange

The previous onYearMonthChange prop is now called onViewChange.

Anchor to Removed propertiesRemoved properties

Anchor to readOnlyreadOnly

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

Anchor to New propertiesNew properties

The Polaris date picker component introduces the following new properties: