Go to Content
Design System
Playroom Storybook
#StandWithUkraine

NewDateInput Beta React-only

Open in Storybook Open in Figma

There are currently four components for entering dates available in GDS. The old ones, DateInput and DateRangeInput are being phased out and it is not recommended to use them anymore.

The future of GDS date entry lies in their successors – NewDateInput and NewDateRangeInput.

HINT We have written a guide on how to migrate the old inputs to the new ones.

HINT There are two more time selection components in GDS: MonthDropdown and YearDropdown.

Loading demo…

Parsing

To provide a friendly user experience, the parsing logic is not configurable.

NewDateInput ignores spaces and understands dates with dots, slashes, and dashes. Leading zeroes are optional and so are trailing dots.

The component understands little-endian date formats well (formats that go in the order of days, months, years), it will however also properly parse an ISO-8601 format (YYYY-MM-DD) and its derivatives. All in all, there are 30 formats supported.

Furthermore, if the user leaves out the year, NewDateInput assumes the current year. Similarly, if the user omits both month and year, the input assumes the current values. So during, say, January 2022 – if the user writes in 23 – NewDateInput immediately parses the value as 23rd of January 2022.

Loading demo…

Formatting

It is possible to define display formats for both the input value and labels in the dropdown.

All these formats are defined in Unicode tokens. Please be careful as these tokens differ from the tokens used by Moment.js and some other libraries.

CAUTION The old components (DateInput and DateRangeInput) are using the Moment.js tokens. Therefore the values in the formatting props are not fully compatible with NewDateInput and NewDateRangeInput.

Loading demo…

Values

NewDateInput and NewDateRangeInput work with JavaScript Date objects.

When the user types in an invalid date, the inputs return a JavaScript Invalid date. In that case, you should render a small Alert letting the user know about the issue.

The inputs intentionally keep the entered value and let the user correct their mistake.

Rules For Developers
  • Values can be set through date (NewDateInput) and startDate and endDate (NewDateRangeInput) props.
  • The inputs return a Date object through onDateChange (NewDateInput) and onDatesChange (NewDateRangeInput) callbacks.
  • When the entered value is invalid, the returned Date object contains a custom attribute invalidString with the raw unparsed value. You may use it to improve the Alert message or to pass it back when using the NewDateInput/NewDateRangeInput as a controlled input.

Buttons

By default, NewDateInput and NewDateRangeInput include a button for opening the calendar. This is not necessary, since the calendar opens when a user focuses the input field. When desired, the button can be omitted.

When the input has a set value, it shows a button to clear it. This button can be hidden as well.

Loading demo…
Rules For Developers
  • It is possible to prevent reopening the calendar by setting reopenPickerOnClearDate to false.

Calendar

The dropdown with the calendar can be tweaked in multiple ways.

Normally, an empty NewDateInput and NewDateRangeInput open their calendars on the current month. This behaviour can be overridden by passing a Date in calendarDefaultDate prop. Doing so is desirable e.g. when there are no allowed dates within the current month.

Allowed dates

By default past dates are disabled and the user can choose dates from today onwards. It is possible to allow or forbid any dates as needed.

Loading demo…
Rules For Developers
  • The isOutsideRange prop expects a function that takes a Date object and returns true when the date should be disabled. (So the date is outside of the allowed range).
  • In the examples, we use date-fns library, which we also use internally. But you are free to implement the isOutsideRange function any way you want.
  • The isOutsideRange prop affects the calendar only. If the user enters a disabled date through the keyboard, the input will accept it and pass it on. In that case, you should display a small Alert explaining to the user that such a date is not allowed along with a reason and invalidate the form.
  • In NewDateRangeInput, the disabled dates cannot be picked as starting or ending dates. It is however still possible to select a range that spans over dates that are outside range.

Range length

NewDateRangeInput is capable of limiting the length of the range user is selecting.

Loading demo…
Rules For Developers
  • It is possible to combine isOutsideRange, minimumNights and maximumNights.
  • The default minimumNights is 1. If you want to let the user select a range that starts and ends on the same day, set minimumNights to 0.

Multiple months

The calendar can display multiple months side by side. This can be especially desired when selecting longer ranges in NewDateRangeInput.

In XS tier the calendar reduces to the current month.

Loading demo…

NewDateInput and NewDateRangeInput have footer slots.

Loading demo…