International Dates

For both storing and passing as values to ink components, the ISO-8601 formats are the ideal. They not only have easy to understand formats like YYYY-MM-DDTHH:MM:SSZ (e.g. 2025-12-31T12:00:00Z), they also have time and time offset information attached to it which facilitates storage.

The ISO-8601 formats avoid ambiguity for easier readability, allow for UTC offsets which help when calculating dates and times across countries, and ensures consistency across systems and locales.

Avoid using moment objects and Date instances as those

Ink date components allow for several formats, including strictly numbered formats (e.g. short and long) and disambiguated formats (e.g. condensed and condensedWithTime).

The disambiguated formats allow for a better user experience through an easier distinction between month and day so, ink encourages you to use the disambiguated formats unless strictly necessary. And in cases that it is necessary to use numbered dates, make sure to indicate somewhere on the UI which format is being used: MM/DD/YYYY or DD/MM/YYYY.

For formats that require time and timezone, always specify a time and timezone to guarantee that the display of the date and time will be consistent across users.

When no specific timezone is provided, the user's system or browser timezone is used and can result and dates and times being displayed differently because of timezone and offset calculations. Also make clear to the user that the timezone being displayed is their own.

When using timezones, always use IANA TZ identifiers (e.g., America/New_York, Asia/Tokyo).

When precision matters, such as in deadlines, events and logs, make sure to always attach date, time and timezone information. When only date is provided, dates and times can change, leading to inconsistencies.

Date components, at this point in time, only allow for en-US and en-GB input and output locales. If your user is outside of the US, prefer using en-GB input/output locale as this will guarantee that inputted dates will be understood as DD/MM/YYYY and not MM/DD/YYYY.

Different combinations of input/output locales lead to different results:

* These are the same as using a single string en-US or en-GB, instead of input/output.

Ink provides a range of formatting components, including a date formatting hook to make sure consistency is met across the codebase. Avoid using other libraries and solutions to format dates.

If a value cannot be processed or formatted, (invalid date, unknown format), show a clear fallback or error message through a custom error prop. Avoid silent failures and make it obvious when something cannot be displayed due to i18n issues.

Make sure ink components accept the necessary formats for your localized product. If that's not the case, reach out to the #ink channel and make your request, or contribute by opening a PR and adding your format. Don't forget to add tests!

Test your UI with various locales and timezones to ensure correct formatting, especially for edge cases like daylight saving time changes to check for spacing, size and other changes that may happen with edge cases.

Let users know when dates and date inputs are locale and timezone sensitive.

If you'd like to know more about how we process dates in ink, feel free to check our dateTimeUtils internal library documentation.