@eds/date-input

v4.1.9

DateInput

Allows the user to enter dates manually or trigger date picker calendar.

Usage

The <DateInput /> component pairs a text input component with a calendar view to help users enter a date.

Controlled

The <DateInput /> is a controlled component so it is required to provide the value and onChange props.

The onChange callback is only fired when a valid date is entered. To get notified when the user has entered an invalid date, use the onBlur callback.

A valid date is one that:

Formats as a valid date.
Isn't a disabled date.
Isn't outside the DateInput's date range.

As the onChange callback only fires when a valid date is selected or entered, the onBlur callback can be used to find out if the user has typed an invalid, disabled or out of range date into the input. It can be useful to provide additional validation information to the user.

The onBlur callback provides the text the user has typed, a Date object if the input is a valid Date object but out of range, and a ValidationError object that contains a validation message as well as which type of validation error has been triggered.

This can be used with a <Field /> component to give users additional feedback.

To see each error in effect, type the following in the below example:

Type an invalid date and blur the input.
Type tomorrow's date which is set as disabled and blur the input.
Type a date outside the current year which is set as the year range limit and blur the input.

For more examples of handling validation see the Validation section.

initialDisplayDate

The initialDisplayDate prop sets the month and year that is displayed in the calendar view when no date has been input.

Defaults to the current month and year.

Limiting viewable years

The fromYear and toYear props limit what years will be shown to the user in the calendar view.

By default the fromYear is set to 1900, and the toYear is set two years into the future.

If a user types a date outside these years it is considered an invalid date.

Disabled dates

The disabledDates prop allows dates to be disabled from selection or input by the user.

It accepts a DateMatcher type which is an array that can contain a single date, an array of dates, a date range, "before" or "after" dates, days of the week, or any combination of the above.

Note that disabledDates will prevent the user from selecting dates, but will not limit what dates are visible. See Limiting viewable years to limit what dates are displayed to the user.

Size

The <DateInput /> supports two sizes, small and medium (default). Prefer using size consistently with other form controls (e.g. a button) that support the same sizes.

Disabled

Use the disabled prop when the user shouldn't be able to manipulate the value of the input.

Invalid

Use the invalid prop to communicate that validation has failed for this particular date input.

Validation

The onBlur handler provides three values, the text input value, the value as a Date if it is a valid date, and a validationError.

The validationError object indicates which type of validation error has occurred which can be used to customise validation error messages to the user.

Type in an invalid or disabled date then blur the input to see the different error messages.


const today = new Date();
const [date, setDate] = useState<Date | undefined>(today);
const [validationMessage, setValidationMessage] = useState<string>();

const onDateChange = (date?: Date) => {
  setDate(date);
  setValidationMessage('');
};

const onBlur = ({ validationError, inputDate, date }: DateValidation) => {
  if (validationError?.outOfRange) {
    setValidationMessage(
      `${date?.toLocaleDateString()} is out of range, please pick a date from ${today.getFullYear()}.`
    );
  } else if (validationError?.disabledDate) {
    setValidationMessage(`${date?.toLocaleDateString()} is not available, please pick a date that is not disabled.`);
  } else if (validationError?.invalidDate) {
    setValidationMessage(
      `${inputDate} is not a valid date, please input a valid date or use the calendar to select a date.`
    );
  }
};

return (
  <Field label="Pick a date" invalid={!!validationMessage} message={validationMessage}>
    <DateInput
      fromYear={today.getFullYear()}
      toYear={today.getFullYear()}
      disabledDates={[today]}
      value={date}
      onChange={onDateChange}
      onBlur={onBlur}
    />
  </Field>
);

Validation with Yup

When using yup and react-hook-form, the onBlur handler can be hooked up to setError to give users more specific feedback if they type in a date incorrectly.

It should be noted that when the user submits the form, the yup validation will take over and provide the error message defined in the yup schema.

DateRangeInput

The <DateRangeInput /> component works similarly as the <DateInput />, but allows the user to select a range between two dates.

Only use the DateRangeInput when both a "from" and "to" date are required. If either the "from" or "to" date is optional, opt to use two DateInputs instead.

The DateRangeInput has the same props as the DateInput, with the exception that the value and onChange props accept and provide a DateRange rather than a Date.

The DateRange object provides a from and a to date.

type DateRange = {
  from: Date | undefined;
  to?: Date | undefined;
};

Valid DateRange

Similar to the DateInput, the DateRangeInput will only call the onChange handler with a DateRange when a valid DateRange has been selected or typed into the input. Otherwise it will return undefined.

It also provides an onBlur callback which provides a validation message when the DateRange is invalid.

To be valid, a DateRange must:

Have at least a "from" date set.
Both from and to must be valid dates.
None of the dates between "from" and "to" can be disabled.
The "from" and "to" dates are within any provided fromYear and toYear values.
The "to" date is after the "from" date.

If only a "from" date is set, or both dates are set but the "to" date is invalid, or the range is invalid, the onChange callback will still pass the range with the "from" value.