Skip to content
lab components / Text

Formatted Date

Present dates and times in a clear, user-friendly format that reflects their locale.

ExamplesGuidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { FormattedDate } from "@siteimprove/fancylab";

#Examples

Consistently display dates and times in a clear, accessible format that aligns with user expectations and regional conventions. This ensures clarity and avoids confusion when presenting temporal information.

Examples:

  • Scheduled reports: 6/25/2024, 02:51 PM
  • User action log: 7/3/2024 4:28:44 PM
  • User creation date: 25/03/2024
  • Last Updated: 2 hours ago
<FormattedDate date={date} locale="en-US" />

#Format

Choose the format that best suits the content type and context.

  • Date: Prioritize unambiguous formats (e.g., "March 25, 2024" or "25 March 2024"). For brevity, consider using abbreviated month names only if space is limited and the context is clear. See examples in Grammar and mechanics > Dates.
  • Time: Use the 12-hour clock (AM/PM) for clarity, especially in less formal contexts. See examples in Grammar and mechanics > Times.


<FormattedDate date={date} locale="en-US" format="time" /> <br /> <FormattedDate date={date} locale="en-US" format="date" /> <br /> <FormattedDate date={date} locale="en-US" format="datetime" />

#Locale

The date and time display pattern varies with each region of the globe. Therefore, the locale parameter allows you to control in which standard the date will be formatted. All standard locale codes defined by the ECMAScript Internationalization API are supported.



<FormattedDate date={date} locale="da-DK" format="datetime" /> <br /> <FormattedDate date={date} locale="en-US" format="datetime" /> <br /> <FormattedDate date={date} locale="pt-BR" format="datetime" />

#Timezone Reset

By default, dates are displayed in UTC. However, this behavior can be changed to display them in your local timezone.

<FormattedDate date={date} locale="en-US" format="datetime" skipTimezoneReset />

#Empty date

When no date or time is available, use a clear placeholder (e.g., "-") and provide an appropriate aria-label for screen reader users (e.g., "Date unavailable").

Unknown date
<FormattedDate date={null} locale="en-US" />

#Guidelines

#Best practices

#General

Use FormattedDate when:

  • You need to display dates and/or times consistently.
  • The date/time information is essential to the content or user task.

#Placement

FormattedDate is typically used in the following places:

  • In Table / List table, displaying the user creation date allows for easy sorting and filtering.
  • Within transaction logs, timestamps provide a detailed audit trail for troubleshooting and analysis.
  • For notifications and alerts, the time received highlights urgency.
  • In report detail, schedule changed times offer clear scheduling information.

#Style

  • Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your FormattedDate to existing components for visual consistency.

#Do not use when

#Accessibility

#For designers

  • Ensure sufficient color contrast between the date/time text and the background.
  • Ensure that the date/time format is clear and unambiguous for users with visual impairments (consider adding an explicit label if necessary).

#For developers

  • This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Follow local conventions for date and time formatting (e.g., "March 25, 2024" in North America, "25 March 2024" in Europe). Follow the date and time guidance .