Date Picker

NOTE: all date components expect their value to be an ISO 8601 date string (without the time signature), which follows the format yyyy-mm-dd

Alternatives

The kind of date (exact, approximate, memorable) you are requesting from the user will determine which component is best to use.

DatePicker

Allows the user to view, type and pick dates from a calendar.

const [value, setValue] = useState();
return (
  <Field label="Pay date">
    <DatePicker
      label="Pay date"
      value={value}
      onChange={setValue}
      onClear={() => setValue(undefined)}
      disabled
    />
  </Field>
);

size

There are three options for the size, "medium" is the default.

const [value, setValue] = useState();
return (
  <Stack gap="large">
    <Field label="Medium (default)">
      <DatePicker
        size="medium"
        value={value}
        onChange={setValue}
        onClear={() => setValue(undefined)}
      />
    </Field>
    <Field label="Small">
      <DatePicker
        size="small"
        value={value}
        onChange={setValue}
        onClear={() => setValue(undefined)}
      />
    </Field>
    <Field label="Large">
      <DatePicker
        size="large"
        value={value}
        onChange={setValue}
        onClear={() => setValue(undefined)}
      />
    </Field>
  </Stack>
);

disabled

Disables the input.

Calendar props

The date picker implements react-day-picker under the hood. A subset of the API is available to influence the calendar appearance and behaviour:

const [value, setValue] = useState();
const today = new Date();
return (
  <Field label="Pay date">
    <DatePicker
      disabledDays={{ before: today }}
      fromMonth={today}
      value={value}
      onChange={setValue}
      onClear={() => setValue(undefined)}
    />
  </Field>
);

Notice that we're disallowing selection of days prior to today using the disabledDays property. We're also disabling navigation to months prior to today using fromMonth because they would not be selectable.

DateRangePicker

The range picker functions much like the DatePicker except it lets the user select or type a date range.

const [value, setValue] = useState();
return (
  <Field label="Pay period">
    <DateRangePicker
      value={value}
      onChange={setValue}
      onClear={() => setValue(undefined)}
    />
  </Field>
);

Size

The DateRangePicker accepts the same "size" property as the DatePicker.

disabled

Disables the input.

Keyboard shortcuts

t

Selects todays date.

CalendarPicker

A simple version of the DatePicker meant to be used for UIs that require filtering instead of forms. It does not have text input.

const [value, setValue] = useState(new Date());
return (
  <CalendarPicker
    label={`Pay date ${value ? `: ${new Date(value).toDateString()}` : ''}`}
    size="small"
    value={value}
    onChange={setValue}
    onClear={() => {
      return setValue(undefined);
    }}
  />
);

CalendarPicker

A simple version of the DateRangePicker meant to be used for UIs that require filtering instead of forms. It does not have text input.

const [value, setValue] = useState<
    | {
        start?: undefined | ISODate;
        end?: undefined | ISODate;
      }
    | undefined
  >(undefined);
  return (
    <CalendarRangePicker
      label={`Pay period ${
        value?.start ? `: ${new Date(value.start).toDateString()} - ` : ''
      } ${value?.end ? `${new Date(value.end).toDateString()}` : ''}`}
      size="small"
      value={value}
      onChange={setValue}
      onClear={() => {
        return setValue(undefined);
      }}
    />
  );

Testing

All date picker components support the data attribute to facilitate testing with automatic testid generation and hierarchical prefixing. When you provide a base testid, the component automatically generates testids for all its interactive elements using that base as a prefix.

For more information on how to use the data attribute, see the Core documentation.

Additionally each balance component will be annotated with a data-balance-component attribute to help identify the boundary of the component in tests.

Selecting these with xpath should be straightforward, as the testids are structured hierarchically. For example, if you set data={{ testid: 'my-component' }}, the generated testids will be prefixed with my-component, making it easy to select specific elements in your tests.

Example XPath Selectors

The date picker balance component which you've set up with a testid of my-component:

//*[@data-balance-component='date-picker' and @data-testid='my-component']

The button of any date picker balance component with a testid of my-component can be selected like this:

//*[@data-testid='my-component--button']

(or if you want to be very specific, you can use the full path)

//*[@data-balance-component='date-picker' and @data-testid='my-component']//*[@data-testid='my-component--button']

DatePicker

The DatePicker supports testids for all its interactive elements:

<DatePicker
  data={{ testid: 'payment-date' }}
  value={value}
  onChange={setValue}
  onClear={() => setValue(undefined)}
/>

This will generate the following testids:

DateRangePicker

The DateRangePicker supports testids for its date range selection elements:

<DateRangePicker
  data={{ testid: 'pay-period' }}
  value={value}
  onChange={setValue}
  onClear={() => setValue(undefined)}
/>

This will generate the following testids:

CalendarPicker

The CalendarPicker supports testids for its button-only date selection:

<CalendarPicker
  data={{ testid: 'filter-date' }}
  value={value}
  onChange={setValue}
  onClear={() => setValue(undefined)}
/>

This will generate the following testids:

CalendarRangePicker

The CalendarRangePicker supports testids for its button-only date range selection:

<CalendarRangePicker
  data={{ testid: 'filter-period' }}
  value={value}
  onChange={setValue}
  onClear={() => setValue(undefined)}
/>

This will generate the following testids: