Date picker

Date pickers let merchants choose dates from a visual calendar that’s consistently applied wherever dates need to be selected across Shopify.

Use when merchants need to select a single day close to today (today is the default starting position for the date picker).

import {DatePicker} from '@shopify/polaris';
import {useState, useCallback} from 'react';

function DatePickerExample() {
  const [{month, year}, setDate] = useState({month: 1, year: 2018});
  const [selectedDates, setSelectedDates] = useState({
    start: new Date('Wed Feb 07 2018 00:00:00 GMT-0500 (EST)'),
    end: new Date('Wed Feb 07 2018 00:00:00 GMT-0500 (EST)'),
  });

  const handleMonthChange = useCallback(
    (month, year) => setDate({month, year}),
    [],
  );

  return (
    <DatePicker
      month={month}
      year={year}
      onChange={setSelectedDates}
      onMonthChange={handleMonthChange}
      selected={selectedDates}
    />
  );
}

Use when merchants need to select a range of days close to today (today is the default starting position for the date picker).

import {DatePicker} from '@shopify/polaris';
import {useState, useCallback} from 'react';

function DatePickerExample() {
  const [{month, year}, setDate] = useState({month: 1, year: 2018});
  const [selectedDates, setSelectedDates] = useState({
    start: new Date('Wed Feb 07 2018 00:00:00 GMT-0500 (EST)'),
    end: new Date('Sat Feb 10 2018 00:00:00 GMT-0500 (EST)'),
  });

  const handleMonthChange = useCallback(
    (month, year) => setDate({month, year}),
    [],
  );

  return (
    <DatePicker
      month={month}
      year={year}
      onChange={setSelectedDates}
      onMonthChange={handleMonthChange}
      selected={selectedDates}
      allowRange
    />
  );
}

Use multi-month mode to show two months at a time.

import {DatePicker} from '@shopify/polaris';
import {useState, useCallback} from 'react';

function DatePickerExample() {
  const [{month, year}, setDate] = useState({month: 1, year: 2018});
  const [selectedDates, setSelectedDates] = useState({
    start: new Date('Wed Feb 07 2018 00:00:00 GMT-0500 (EST)'),
    end: new Date('Mon Mar 12 2018 00:00:00 GMT-0500 (EST)'),
  });

  const handleMonthChange = useCallback(
    (month, year) => setDate({month, year}),
    [],
  );

  return (
    <DatePicker
      month={month}
      year={year}
      onChange={setSelectedDates}
      onMonthChange={handleMonthChange}
      selected={selectedDates}
      multiMonth
      allowRange
    />
  );
}

Date ranges may be disabed if you do not want them to be selectable

import {DatePicker} from '@shopify/polaris';
import {useState, useCallback} from 'react';

function DatePickerExample() {
  const [{month, year}, setDate] = useState({month: 1, year: 2018});
  const [selectedDates, setSelectedDates] = useState({
    start: new Date('Wed Feb 07 2018 00:00:00 GMT-0500 (EST)'),
    end: new Date('Sat Feb 10 2018 00:00:00 GMT-0500 (EST)'),
  });

  const handleMonthChange = useCallback(
    (month, year) => setDate({month, year}),
    [],
  );

  return (
    <DatePicker
      month={month}
      year={year}
      onChange={setSelectedDates}
      onMonthChange={handleMonthChange}
      selected={selectedDates}
      disableDatesBefore={new Date('Sat Feb 03 2018 00:00:00 GMT-0500 (EST)')}
      disableDatesAfter={new Date('Sun Feb 18 2018 00:00:00 GMT-0500 (EST)')}
      allowRange
    />
  );
}

Dates may be disabed if you do not want them to be selectable

import {DatePicker} from '@shopify/polaris';
import {useState, useCallback} from 'react';

function DatePickerExample() {
  const [{month, year}, setDate] = useState({month: 1, year: 2018});
  const [selectedDates, setSelectedDates] = useState(
    new Date('Wed Feb 07 2018 00:00:00 GMT-0500 (EST)'),
  );

  const handleMonthChange = useCallback(
    (month, year) => setDate({month, year}),
    [],
  );

  const browserTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;

  const disableSpecificDates = [
    new Date('Mon Feb 12 2018 00:00:00 GMT-0500 (EST)'),
    new Date('Sat Feb 10 2018 00:00:00 GMT-0500 (EST)'),
    new Date('Wed Feb 21 2018 00:00:00 GMT-0500 (EST)'),
  ];

  return (
    <DatePicker
      month={month}
      year={year}
      onChange={setSelectedDates}
      onMonthChange={handleMonthChange}
      selected={selectedDates}
      disableDatesBefore={new Date('Sat Feb 03 2018 00:00:00 GMT-0500 (EST)')}
      disableDatesAfter={new Date('Sun Feb 25 2018 00:00:00 GMT-0500 (EST)')}
      disableSpecificDates={disableSpecificDates}
    />
  );
}

Props

Want to help make this feature better? Please share your feedback.

interface DatePickerProps
id?string

ID for the element.

selected?Range | Date

The selected date or range of dates.

monthnumber

The month to show, from 0 to 11. 0 is January, 1 is February ... 11 is December.

yearnumber

The year to show.

allowRange?boolean

Allow a range of dates to be selected.

disableDatesBefore?Date

Disable selecting dates before this.

disableDatesAfter?Date

Disable selecting dates after this.

disableSpecificDates?Date[]

Disable specific dates.

multiMonth?boolean

The selection can span multiple months.

weekStartsOn?number

First day of week, from 0 to 6. 0 is Sunday, 1 is Monday ... 6 is Saturday.

Defaults to 0.

dayAccessibilityLabelPrefix?string

Visually hidden prefix text for selected days on single selection date pickers.

onChange?(date: Range) => void

Callback when date is selected.

onMonthChange?(month: number, year: number) => void

Callback when month is changed.

Best practices

Date pickers should:

  • Use smart defaults and highlight common selections
  • Close after a single date is selected unless a range with a start and end date is required
  • Set the start date on first click or tap and the end date on second click or tap if a range is required
  • Not be used to enter a date that is many years in the future or the past
  • Follow date format guidelines

Accessibility

Some users might find interacting with date pickers to be challenging. When you use the date picker component, always give users the option to enter the date using a text field component as well.

If you use the date picker within a popover component, then use a button to trigger the popover instead of displaying the popover when the text input gets focus. This gives users more control over their experience.

Keyboard support

  • Press the tab key to move forward and shift + tab to move backward through the previous button, next button, and the calendar
  • When focus is in the calendar, move keyboard focus between the dates using the arrow keys
  • To select a date that has focus, press the enter/return key