Date

Dates give the user consistent stylized and accessible representations of a date.

General Guidelines

The date component provides a standard way to express a numeric calendar date, that eliminates ambiguity. The date component provides consistent formats with which to represent the date. The different formats we use are applied based on the needs of their usage (for example : stacked or linear, depending upon space and style requirements).

Grammar and Mechanics

  • Refrain from using the date in an entirely numeric format in order to eliminate any possible confusion for the user, as date formatting differs around the world.
  • The date should be displayed with four digits, to clearly represent the century, decade, and year.
  • Display the month by name in a three letter abbreviated format (for example JAN for January).
  • Display the month in ALL CAPS.
  • The day should be represented with two digits even when the number is below ten (for example: 03).

Usage

Configurations When
Use stacked dates For records that have more than one line of information.
Use stacked dates When the date is the first thing on the left hand side of a record.
Use dates in a linear format When you need to display a full date in a single line.

Do's and Don'ts

Do always show the date with two digits
Do format dates as month, day, year for linear usages
Don’t use a linear format when there are multiple lines of record information
Don’t use formats other than those given in the code and style sections
Dates give the user consistent stylized and accessible representations of a date.

spacing, size, padding, and typography

Dates give the user consistent stylized and accessible representations of a date.

Examples

For details on when to use this component, please see the Usage tab.

The variants of this component are as follows:

Stacked Full Date

<div class="iris-date iris-date--stacked-full" data-datetime="2017-10-28"></div>

In some cases you may not have the year in the date. You can use the data-dateformat attribute to do that.

<div class="iris-date iris-date--stacked-full" data-datetime="2017-10-28" data-dateformat="MD"></div>

Stacked Month and Year

<div class="iris-date iris-date--stacked-month-year" data-datetime="2017-10-28"></div>

Linear Full Date

<div class="iris-date iris-date--linear" data-datetime="2017-10-28"></div>

In some cases you might want to remove the year at the end. You can use the data-dateformat attribute to do that.

<div class="iris-date iris-date--linear" data-datetime="2017-10-28" data-dateformat="DM"></div>

Static Date

You don't have to use data-datetime. Instead, you can format the values yourself. Be mindful that you will need to add an aria-label attribute with the full date so that screen readers will pronounce the date correctly.

28 Oct 2017
<div class="iris-date iris-date--stacked-full" aria-label="October 28th, 2017">
    <span class="iris-date__day">28</span>
    <span class="iris-date__month">Oct</span>
    <span class="iris-date__year">2017</span>
</div>

The DateFormat Attribute

The Date Time attribute can be used to override the default behaviors of the available variants. The attribute accepts a string with any variation of the letters D, M , and Y. The most common variations of these are used in the iris-date--stacked-full variant and the iris-date--linear, allowing you to remove the year when needed. Here are those examples.

<div class="iris-date iris-date--stacked-full" data-datetime="2017-10-28" data-dateformat="MD"></div>
<div class="iris-date iris-date--linear" data-datetime="2017-10-28" data-dateformat="DM"></div>

Using other DateTime Formats

The Date Component supports several formats for the data-datetime attribute.

  • ISO 8601 date format. e.g. 2017-10-28
  • ISO 8601 date-time format. e.g. 2017-10-28T00:00:00.000Z
  • ISO 2822 dates. e.g. 28 Oct 2010
  • ISO 2822 date-time. e.g. 28 Oct 2017 00:00:00 GMT

Other formats may work but should be avoided due to browser inconsistencies.

Accessibility

As always, we want all of the components in the application to be accessible. Please keep the following notes in mind while using this component:

  • An aria-label="<Formatted Date in Datetime>" is added to all dates with data-datetime.

Variables

The variables used in this component are as follows:

// Text variables
$date-month-color: $dove-gray !default;
$date-day-color: $dove-gray !default;
$date-year-color: $dove-gray !default;

Themeability

Nothing is themeable in this component.

Variant: Stacked Full | State: None | Decorator: None

October 28, 2017
<div class="iris-date iris-date--stacked-full">
    <span class="iris-date__full-date">October 28, 2017</span>
    <span class="iris-date__month" aria-hidden="true">Oct</span>
    <span class="iris-date__day" aria-hidden="true">28</span>
    <span class="iris-date__year" aria-hidden="true">2017</span>
</div>
Variant: Stacked Month and Year | State: None | Decorator: None

October 28, 2017
<div class="iris-date iris-date--stacked-month-year">
    <span class="iris-date__full-date">October 28, 2017</span>
    <span class="iris-date__month" aria-hidden="true">Oct</span>
    <span class="iris-date__year" aria-hidden="true">2017</span>
</div>
Variant: Linear | State: None | Decorator: None

October 28, 2017
<div class="iris-date iris-date--linear">
    <span class="iris-date__full-date">October 28, 2017</span>
    <span class="iris-date__day" aria-hidden="true">28</span>
    <span class="iris-date__month" aria-hidden="true">Oct</span>
    <span class="iris-date__year" aria-hidden="true">2017</span>
</div>