Skip to main content
Version: 4.0 (next)

Date, time, duration, and age scenarios

Choose a focused guide​

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 source demonstrates common display boundaries with explicit comparison values and culture:

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 offsetComparison = new DateTimeOffset(comparison);
var offsetRelative = offsetComparison.AddDays(-1).Humanize(offsetComparison, culture);
var dateOnlyComparison = new DateOnly(2025, 1, 20);
var dateOnlyRelative = dateOnlyComparison.AddDays(-1).Humanize(dateOnlyComparison, culture);
var timeOnlyComparison = new TimeOnly(12, 0);
var timeOnlyRelative = timeOnlyComparison.AddMinutes(1).Humanize(timeOnlyComparison, culture: culture);
var duration = TimeSpan.FromMinutes(125).Humanize(precision: 2, culture: culture);

Console.WriteLine($"DateTime: {relative}");
Console.WriteLine($"DateTimeOffset: {offsetRelative}");
Console.WriteLine($"DateOnly: {dateOnlyRelative}");
Console.WriteLine($"TimeOnly: {timeOnlyRelative}");
Console.WriteLine($"Duration: {duration}");
Output
DateTime: yesterday
DateTimeOffset: yesterday
DateOnly: yesterday
TimeOnly: a minute from now
Duration: 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.

Keep clocks and calendars explicit​

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.