accessible-date

accessible-date

accessible-date is an npm module that creates readable, accessible dates for screen readers. These dates are returned in Coordinated Universal Time (UTC), and are currently available in English, Spanish, French, and Italian with more languages to come.

Screen readers have a hard time deciphering what is and isn’t a date in HTML. For example, if a screen reader comes across the following timestamp:

<time id="timestamp" datetime="2001-05-15T19:30">May 15, 2001 - 7:30pm</time>

… the screen reader will read it as the following:

May one five, two zero zero one, seven three zero p m

accessible-date can change the format of a timestamp into something readable:

Tuesday, May fifteenth, two-thousand one at seven thirty p m

accesible-date can also process dates into military time as well:

Tuesday, May fifteenth, two-thousand one at zero seven thirty

Installation

NOTE: As of version 2.0.0 of accessible-date, we are now using native JavaScript import/exports. If you would like to require this module, you need to use versions 1.3.0 or earlier.

You can install the module through npm:

npm install accessible-date --save

Then just import the module into your JavaScript file, and give it a timestamp and a settings object hash of options:

import accessibleDate from "accessible-date";
const timestampElem = document.getElementById("timestamp");
const newAccessibleDate = accessibleDate(timestampElem.getAttribute("datetime"), {
    format: `DD, M D, Y at H MM m`,
    language: `en`,
    military: false
});

Then, you can assign that date as, for example, an aria-label to a <time> element:

timestampElem.setAttribute('aria-label', newAccessibleDate);

You will end up with a time attribute like this:

<time id="timestamp" datetime="2001-05-15T19:30" aria-label="Tuesday, May fifteenth, two-thousand one at seven thirty p m">May 15, 2001 - 7:30pm</time>

Parameters and Options

accessible-date takes two parameters: a timestamp and a settings object hash.

The timestamp needs to be in one of the following formats:

2001-05-15T19:30
2018-05-15T19:30:00Z
2018-05-31T07:30:00-02:00
2015-03-25
Wed Mar 25 2015 09:56:24 GMT+0100 (W. Europe Standard Time)

The settings object hash takes the following methods:

settings.format - required How the returned string is formatted. You can use any combination of the following values:

• DD - Day (ex: “Sunday,” “Monday,” etc)
• MM - Minute (ex: “Twelve,” “Thirteen,” etc)
• M - Month (ex: “January,” “February,” etc)
• D - Date (ex: “First,” “Second,” etc)
• Y - Year (ex: “Two thousand seventeen,” “Two thousand eighteen,” etc)
• H - Hour (ex: “Eleven,” “Twelve,” etc)
• S - Second (ex: “Twenty-eight,” “Twenty-nine,” etc)
• m - Meridian (ex: “A M,” “P M”)

settings.language - default en Set the language you want the output to be formatted to. Currently, it supports English (en), Spanish (es), French (fr), and Italian (it), but more languages will continue to be added.

settings.military - default false If set to true, date will display in military time. Otherwise, it defaults to displaying in standard time.

Adding Extra Words

accessible-date takes care of the values mentioned above in settings.format, but words outside of those values should be added on your own. For example, to speak the time in French, you would add the word "heures" after saying the hour as a number. Simply add that into the settings.format string, and accessible-date will ignore that value when parsing through the string.

Changelog

[2.1.1] - 2024-01-07

Changed

• Changed all instances of deprecated substr() to substring().
• Changed some lets to consts.