Skip to main content
Version: 3.0.10 (latest)

Date, time, duration, and age scenarios

Orientation​

Choose the guide by the meaning of the value and the sentence you need:

TaskFocused guide
Produce “yesterday” or “3 hours ago”Relative dates and times
Produce “2 hours, 5 minutes” or an age phraseDurations and ages
Build a readable TimeSpan, DateTime, or DateOnlyFluent dates and time spans
Produce “January 25th, 2022” or “twenty-five past one”Spoken dates and clock times

Example​

This verified source demonstrates the two most common display boundaries: a relative UTC date with an injected comparison instant and a two-unit elapsed duration:

Program.cs
using System.Globalization;
using Humanizer;

var culture = CultureInfo.GetCultureInfo("en-US");
CultureInfo.CurrentCulture = culture;
CultureInfo.CurrentUICulture = culture;

var comparison = new DateTime(2025, 1, 20, 12, 0, 0, DateTimeKind.Utc);
var relative = comparison.AddDays(-1).Humanize(
    utcDate: true,
    dateToCompareAgainst: comparison,
    culture: culture);
var duration = TimeSpan.FromMinutes(125).Humanize(precision: 2, culture: culture);

AssertEqual("yesterday", relative);
AssertEqual("2 hours, 5 minutes", duration);

Console.WriteLine($"{relative}; {duration}");

static void AssertEqual(string expected, string actual)
{
    if (actual != expected)
        throw new InvalidOperationException($"Expected '{expected}', got '{actual}'.");
}

It prints yesterday; 2 hours, 5 minutes. Follow the focused guides for the full overload contracts.

Pick a model before an API​

  • Use DateTimeOffset when an instant and offset matter.
  • Use DateOnly for a calendar date without time-zone meaning.
  • Use TimeOnly for a wall-clock time without a date.
  • Use TimeSpan for elapsed duration, not calendar arithmetic.

Pitfall​

Reading Now inside formatting makes examples, tests, and cache behavior unstable. Inject comparison values and set culture explicitly. A TimeSpan has no calendar context, so months, years, and ages are approximations; use date arithmetic when leap years, month length, or birthdays must be exact.

Version notes​

DateTime, DateTimeOffset, and TimeSpan calls span the supported corpus. DateOnly and TimeOnly humanization begin in 2.11.10; clock notation begins in 2.13.14; ToAge begins in 3.0.1. Historical sidebars must omit unavailable focused guides.