Colored Date Formatter

Colored Date Formatter makes dates and date ranges easier to understand at a glance. Choose a single color for all dates or assign different colors to dates based on their status: past, today, soon, upcoming or ongoing. Highlight overdue deadlines in red, draw attention to dates approaching soon, and distinguish events that are currently in progress, all through Manage display, without writing code.

Use it for task deadlines, event schedules, expiry and renewal dates, application windows, and any other situation where the timing matters.

Features

• Color-coded date statuses:
  • Past: before today.
  • Today: the current day.
  • Soon: within a configurable number of days.
  • Upcoming: beyond the soon period.
  • Ongoing: a date range that has started but has not yet ended.

  Prefer a simpler look? Apply a single color to all dates instead.

• Custom labels: Choose a color and label for each status, with options such as "Overdue", "Due today" and "Due soon".
• Accessible by design: Display status labels, hide them visually while keeping them available to screen readers, or omit them. Status is not communicated through color alone when labels are enabled. Default colors meet WCAG AA contrast requirements against white, and dates use the semantic <time datetime="..."> element.
• Relative dates: Display text such as "in 3 days", "yesterday" or "ends in 2 days" alongside the date or in a tooltip.
• Badge styling: Give dates a tinted background with rounded corners.
• Flexible date formats: Use the site's configured date formats or define a custom PHP date format.
• Date range support: Display both the start and end dates with a configurable separator. When both dates are the same, display the date only once.
• Time zone awareness: Calculate date statuses using the visitor's time zone or a configured time zone override. Dates without a time remain consistent across time zones.
• Time-aware caching: Cache output according to the date's status and refresh it at the next midnight when necessary.
• Theme-friendly markup: Use the provided Twig template, status-specific CSS classes and CSS custom properties to customize the appearance centrally.

Requirements

• Drupal 10.3 or later, including Drupal 11.
• The core Datetime module. Enable the core Datetime Range module when using date range fields.

Installation

Install the module using Composer, then enable it with Drush. For more information, see the Drupal documentation on installing modules.

composer require drupal/colored_date_formatter
drush pm:enable colored_date_formatter

Configuration

1. Navigate to Structure » Content types » [type] » Manage display.
2. For a Date or Date range field, select the Colored date formatter.
3. Click the gear icon to configure the formatter:
   • Select a date format or choose Custom.
   • Choose One color or By status to configure colors and labels for individual statuses.
   • Set the number of days that qualify as soon (7 days by default).
   • Choose whether status labels are visible, visually hidden, or omitted.
   • Configure relative date text and optional badge styling.
4. Save the display settings.

Theming

The formatter produces semantic markup with status classes and optional status and relative-date labels. For example:

<span class="cdf-date cdf-date--past cdf-dark-red cdf-date--badge">
  <time datetime="2026-01-31">31 January 2026</time>
  <span class="cdf-date__status">Overdue</span>
  <span class="cdf-date__relative">(3 days ago)</span>
</span>

• Style by status: Every date receives a status class, such as cdf-date--past, even when a single color is selected. Choose None for the color to handle all status styling in your theme.
• Centralize colors: Override a color through its CSS custom property, for example: .cdf-dark-red { --cdf-color: #a00; }.
• Customize the markup: Override colored-date-formatter.html.twig in your theme for complete control over the output.

A note on caching

The formatter's cache metadata allows status-dependent output to be refreshed at midnight. However, Drupal's Internal Page Cache can retain entire pages for anonymous visitors beyond that point, so displayed statuses may become outdated. To reduce this risk, configure an appropriate page cache maximum age under Configuration » Development » Performance or use a caching layer that respects cache max-age.

Upgrading from 1.0

• Existing display configurations retain their selected colors and date formats.
• Date and time output now respects the correct time zone, fixing cases where version 1.0 could display an incorrect time or day.
• Date range fields now display both the start and end dates.

Support

Found a bug or have an idea for an improvement? Report it or request a feature in the issue queue.