## Usage

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

```tsx live
const [date, setDate] = useState<Date>();

return <DateInput value={date} onChange={setDate} />;
```

## 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](#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.

## onBlur

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.

```tsx live
const [validationMessage, setValidationMessage] = useState<string>();
const [date, setDate] = useState<Date>();

const onBlur = ({ validationError }: DateValidation) => {
  setValidationMessage(validationError?.message);
};

const tomorrow = new Date(Date.now() + 86400000);

return (
  <Field label="Enter a date" invalid={!!validationMessage} message={validationMessage}>
    <DateInput
      value={date}
      onChange={setDate}
      onBlur={onBlur}
      fromYear={new Date().getFullYear()}
      toYear={new Date().getFullYear()}
      disabledDates={[tomorrow]}
    />
  </Field>
);
```

For more examples of handling validation see the [Validation](#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.

```tsx live
const [date, setDate] = useState<Date>();

return <DateInput value={date} onChange={setDate} initialDisplayDate={new Date(1983, 2, 1)} />;
```

## 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 100 years in the past, and the `toYear` is set 100 years into the future.

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

```tsx live
const [date, setDate] = useState<Date>();

return <DateInput value={date} onChange={setDate} fromYear={1979} toYear={1980} />;
```

## 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](#limiting-viewable-years) to limit what dates are displayed to the user.

```tsx live
const [dateMultiple, setDateMultiple] = useState<Date>();
const [dateRange, setDateRange] = useState<Date>();
const [dateBeforeAfter, setDateBeforeAfter] = useState<Date>();
const [dateDayOfWeek, setDateDayOfWeek] = useState<Date>();

return (
  <Flex flexDirection="column" gap="large">
    <Field label="Multiple single-dates">
      <DateInput
        value={dateMultiple}
        onChange={setDateMultiple}
        initialDisplayDate={new Date(2023, 3, 1)}
        disabledDates={[
          new Date(2023, 3, 5),
          new Date(2023, 3, 6),
          new Date(2023, 3, 8),
          new Date(2023, 3, 10),
          new Date(2023, 3, 11),
          new Date(2023, 3, 12),
        ]}
      />
    </Field>

    <Field label="Date range">
      <DateInput
        value={dateRange}
        onChange={setDateRange}
        initialDisplayDate={new Date(2023, 3, 1)}
        disabledDates={[{ from: new Date(2023, 3, 3), to: new Date(2023, 3, 16) }]}
      />
    </Field>

    <Field label="Before & after">
      <DateInput
        value={dateBeforeAfter}
        onChange={setDateBeforeAfter}
        initialDisplayDate={new Date(2023, 3, 1)}
        disabledDates={[{ before: new Date(2023, 3, 10) }, { after: new Date(2023, 3, 14) }]}
      />
    </Field>

    <Field label="Days of the week">
      <DateInput
        value={dateDayOfWeek}
        onChange={setDateDayOfWeek}
        initialDisplayDate={new Date(2023, 3, 1)}
        disabledDates={[{ dayOfWeek: [0, 6] }]}
      />
    </Field>
  </Flex>
);
```

## 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.

```tsx live
const [date, setDate] = useState<Date | undefined>(new Date(2022, 2, 2));

return (
  <Flex flexDirection="column" gap="small">
    <DateInput value={date} onChange={setDate} size="small" />
    <DateInput value={date} onChange={setDate} />
  </Flex>
);
```

## Disabled

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

```tsx live
const [date, setDate] = useState<Date>();

return <DateInput value={date} onChange={setDate} disabled />;
```

## Invalid

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

```tsx live
const [date, setDate] = useState<Date>();

return <DateInput value={date} onChange={setDate} invalid />;
```

## Validation

The [onBlur](#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.

```tsx live open
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.

```tsx live
const [submittedValue, setSubmittedValue] = useState('');

// Get the start and end of the week dates for validation.
const today = new Date();
const monday = new Date(today.setDate(new Date().getDate() - ((new Date().getDay() + 6) % 7)));
const sunday = new Date(today.setDate(today.getDate() + 6));

// Use the disabled dates in our Yup validation and the DateInput.
const disabledDates = [{ before: monday }, { after: sunday }];

const schema = yup.object({
  date: yup.date().required('Please enter a valid date.'),
});

type InputTypes = yup.InferType<typeof schema>;

const {
  handleSubmit,
  formState: { errors },
  control,
  setError,
} = useForm<InputTypes>({
  mode: 'onBlur',
  resolver: yupResolver(schema),
});

const onSubmit = (values: InputTypes) => {
  setSubmittedValue(JSON.stringify(values));
};

return (
  <Flex as="form" flexDirection="column" gap="medium" maxWidth="25rem" onSubmit={handleSubmit(onSubmit)}>
    <Field label="Pick a date from this week" invalid={!!errors.date} message={errors?.date?.message}>
      <Controller
        name="date"
        control={control}
        render={({ field }) => {
          const { onChange, value, onBlur } = field;

          return (
            <DateInput
              fromYear={today.getFullYear()}
              toYear={today.getFullYear()}
              disabledDates={disabledDates}
              value={value}
              onChange={onChange}
              onBlur={({ date, validationError }) =>
                validationError ? setError('date', { message: validationError.message }) : onBlur()
              }
            />
          );
        }}
      />
    </Field>

    <Button type="submit" label="Submit" />

    {submittedValue && <ResponseBlock value={submittedValue} />}
  </Flex>
);
```

## DateRangeInput

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

```tsx live
const [dateRange, setDateRange] = useState<DateRange>();

return <DateRangeInput value={dateRange} onChange={setDateRange} />;
```

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.

```ts
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.

### Props

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

```tsx live
const [dateRange, setDateRange] = useState<DateRange>();

return (
  <Flex flexDirection="column" width="25rem">
    <Field label="Small size">
      <DateRangeInput value={dateRange} onChange={setDateRange} size="small" />
    </Field>

    <Field label="Disabled">
      <DateRangeInput value={dateRange} onChange={setDateRange} disabled />
    </Field>

    <Field label="Invalid">
      <DateRangeInput value={dateRange} onChange={setDateRange} invalid />
    </Field>

    <Field label="Initial display date">
      <DateRangeInput value={dateRange} onChange={setDateRange} initialDisplayDate={new Date(1983, 3, 1)} />
    </Field>

    <Field label="Disabled dates">
      <DateRangeInput
        value={dateRange}
        onChange={setDateRange}
        initialDisplayDate={new Date(2023, 3, 1)}
        disabledDates={[{ from: new Date(2023, 3, 3), to: new Date(2023, 3, 9) }]}
      />
    </Field>
  </Flex>
);
```

### Field example

```tsx live
const [validationMessage, setValidationMessage] = useState<string>();
const [dateRange, setDateRange] = useState<DateRange>();

const onBlur = ({ validationError }: DateValidation) => {
  setValidationMessage(validationError?.message);
};

const tomorrow = new Date(Date.now() + 86400000);

return (
  <Field label="Select a date range" invalid={!!validationMessage} message={validationMessage}>
    <DateRangeInput
      value={dateRange}
      onChange={setDateRange}
      onBlur={onBlur}
      fromYear={new Date().getFullYear()}
      toYear={new Date().getFullYear()}
      disabledDates={[tomorrow]}
    />
  </Field>
);
```

### Date range validation with Yup

```tsx live
const [submittedValue, setSubmittedValue] = useState('');

// Get the start and end of the week dates for validation.
const today = new Date();
const monday = new Date(today.setDate(new Date().getDate() - ((new Date().getDay() + 6) % 7)));
const sunday = new Date(today.setDate(today.getDate() + 6));

// Disable all dates before and after the current week.
const disabledDates = [{ before: monday }, { after: sunday }];

const schema = yup.object({
  dateRange: yup
    .object()
    .shape({
      from: yup.date().required('Please enter a valid "from" date.'),
      to: yup.date().required('Please enter a valid "to" date.'),
    })
    .default(undefined)
    .required('Please enter a valid date range.'),
});

type InputTypes = yup.InferType<typeof schema>;

const {
  handleSubmit,
  formState: { errors },
  control,
} = useForm<InputTypes>({
  mode: 'onBlur',
  resolver: yupResolver(schema),
});

const onSubmit = (values: InputTypes) => {
  setSubmittedValue(JSON.stringify(values));
};

return (
  <Flex as="form" flexDirection="column" gap="medium" maxWidth="25rem" onSubmit={handleSubmit(onSubmit)}>
    <Field
      label="Pick a date range"
      invalid={!!errors.dateRange}
      message={errors?.dateRange?.message || errors?.dateRange?.from?.message || errors.dateRange?.to?.message || ''}
    >
      <Controller
        name="dateRange"
        control={control}
        render={({ field }) => {
          const { onChange, value, onBlur } = field;

          return (
            <DateRangeInput
              fromYear={today.getFullYear()}
              toYear={today.getFullYear()}
              disabledDates={disabledDates}
              value={value}
              onChange={onChange}
              onBlur={onBlur}
            />
          );
        }}
      />
    </Field>

    <Button type="submit" label="Submit" />

    {submittedValue && <ResponseBlock value={submittedValue} />}
  </Flex>
);
```

## Resources

- [ARIA Authoring Practices Guide - Date Picker Dialog Example](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/)
- [React DayPicker](https://react-day-picker.js.org/)

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

DateInput

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources