DateInput

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

Show codeCopy code

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.

Show codeCopy code

For more examples of handling validation see the Validation section.

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.

Show codeCopy code

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.

Show codeCopy code

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.

Show codeCopy code

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.

Show codeCopy code

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

Show codeCopy code

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

Show codeCopy code

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.

Hide codeCopy code
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>
);

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.

Show codeCopy code

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

Show codeCopy code

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

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.

The <DateRangeInput /> has the same option props as the DateInput.

Show codeCopy code

Show codeCopy code

Show codeCopy code

• ARIA Authoring Practices Guide - Date Picker Dialog Example
• React DayPicker