Date & time
Date and time formats are used as timestamps on pay runs, dates within the calendar, employee milestones, and to help the user understand when something happened.
The date-fns package is used to render the time and date formats in Balance. While the library provides more formats, the versions outlined in this page should be the formats used. The library also provides international formats for dates and times, these examples will only address AU formats.
Best practices
When referring to a different time zone, include the abbreviated version of the time zone, e.g. Today at 1:25 pm AEDT. When using relative time, at some determined point, the date will switch to the month, day, year or numerical format. e.g. Today at 1:25 pm would switch to Aug 16, 2019 1:25 pm or 16/08/2019 1:25 pm.
Date formats
Dates may be formatted in the following ways:
| Format | When to use | Example |
|---|---|---|
| Month, Day, Year | When referring to a specific day of the month | 16 August, 2019 |
| Numerical | Space saving format for day of the month | 16/08/2019 |
| Weekday | When referring to a specific day of the week | Friday, 16 August, 2019 |
| Weekday, Numerical | Space saving format for day of the week | Friday, 16/08/2019 |
Time formats
Times may be formatted in the following ways:
| Format | When to use | Example |
|---|---|---|
| Time | When referring to a specific point in time | 1:25 pm |
| Time + Time Zone | When time zone is required | 1:25 pm AEDT |
Date & time
Times can be appended to any Date Format, except Calendar formats:
| Format | When to use | Example |
|---|---|---|
| Month, Day, Year | When referring to a specific day of the month and timestamp | 16 August, 2019 1:25 pm |
| Numerical | Space saving format for day of the month and timestamp | 16/08/2019 1:25 pm |
| Weekday | When referring to a specific day of the week and timestamp | Friday, 16 August, 2019 1:25 pm |
| Weekday, Numerical | Space saving format for day of the week and timestamp | Friday, 16/08/2019 1:25pm |
Date ranges
Date and time ranges may be formatted in the following ways:
| Format | When to use | Example |
|---|---|---|
| d MMM, yyyy – d MMM, yyyy | Range across different years | 16 Aug, 2019 – 16 Oct, 2020 |
| d MMM – d MMM, yyyy | Range within the same year | 16 Aug – 16 Oct, 2019 |
| d – d MMM, yyyy | Range within the same month | 16 – 17 Aug, 2019 |
Special cases
There are special use cases for time and date formats, those should only be used in the specific behaviors outlined:
| Format | When to use | Example |
|---|---|---|
| Month, Year | For use in Calendar (month view) | April 2019 |
| Day Name | For use in Calendar (month view) | Thursday |
| Day Name, Numerical Day | For use in Calendar (week view) | Thursday 28 |
| Computerized | For use in CSV exports | 2019-08-15 1:25 pm |
| Time Zones* | For use when time zone is required | AEDT |
*Time Zone can be appended to any time & date format.
Relative Time
There are other ways to refer to date and time, these may be formatted in the following ways:
| Format | When to use | Example |
|---|---|---|
| Hours | When referring to the hour(s) past, up to 24 hours ago | an hour ago, 2 hours ago etc. |
| Day | When referring to the day or days past, up to 7 days ago | a day ago, 2 days ago etc. |
| Today | When referring the current day | Today at 1:25pm |
| Yesterday | When referring the previous day | Yesterday at 1:25 pm |
| This | When referring to the current year, month, week, day | This week, This month etc. |
| Last | When referring to the previous month, week, day | Last month, Last week, etc. |
| Future | When referring to a month, week, day in the future | 3 days from now |