GuideWriting templates

Working with time zones

This guide explains how time zones work in Fluid templates, covering parsing, rendering, and conversion of date/time values.

Understanding Time Zone BehaviorLink to this heading

In Fluid, time zones affect two different operations:

  1. Parsing: When converting strings to DateTime values
  2. Rendering: When displaying DateTime values in templates

Important: The TimeZone property in TemplateContext and TemplateOptions is used only for parsing, not for rendering. This is a common source of confusion.

What Happens During ParsingLink to this heading

When you parse a date string that doesn't include time zone information:

var context = new TemplateContext
{
    TimeZone = TimeZoneInfo.FindSystemTimeZoneById("America/New_York")
};

// This string has no time zone information
var input = StringValue.Create("2022-12-13T21:02:18.399");

// The date filter will parse it assuming the context's TimeZone
var result = await MiscFilters.Date(input, new FilterArguments(), context);

In this case:

  • The string "2022-12-13T21:02:18.399" has no time zone
  • Fluid assumes it represents a time in the America/New_York time zone
  • The resulting DateTimeOffset will have the offset for New York (-05:00 in winter, -04:00 in summer)

If the string already includes time zone information:

// This string includes time zone information (+00:00)
var input = StringValue.Create("2022-12-13T21:02:18.399+00:00");

// The context's TimeZone is ignored - the string's time zone is used
var result = await MiscFilters.Date(input, new FilterArguments(), context);

What Happens During RenderingLink to this heading

When rendering a DateTime value, Fluid displays it in its own time zone, not the context's time zone:

var date = new DateTime(2022, 2, 2, 12, 0, 0, DateTimeKind.Utc);
var timezone = TimeZoneInfo.FindSystemTimeZoneById("Europe/Uzhgorod");

var context = new TemplateContext(data, new TemplateOptionsBuilder()
    .WithTimeZone(timezone) // This does NOT affect rendering!
    .Build());

var template = parser.Parse("{{ BirthDate }}");
var result = template.Render(context);
// Output: "2022-02-02 12:00:00 UTC" (UTC, not Europe/Uzhgorod)

Like a Ruby Time in Liquid, a moment renders with its own offset, like 2022-02-02 14:00:00 +0200 for a DateTimeOffset at +02:00, or with UTC for a DateTime of Utc kind, like Ruby's Time.utc. The date is rendered in UTC because that's what the DateTime object contains. The context's TimeZone property has no effect on rendering.

Breaking change: a moment was rendered in UTC with the universal sortable format, whatever its offset: 2022-02-02 12:00:00Z.

Dates and Times Without a Time ZoneLink to this heading

A DateTime of Unspecified kind, a DateOnly and a TimeOnly are clock readings rather than moments, like a date read from a database column without offset. Fluid keeps them as they are, a PlainDateTimeValue, and reads them in the time zone of the context only when a date filter needs a moment, whatever the time zone of the machine:

var context = new TemplateContext
{
    TimeZone = TimeZoneInfo.FindSystemTimeZoneById("America/New_York")
};

context.SetValue("starts", new DateTime(2026, 3, 4, 13, 0, 0)); // Unspecified kind
context.SetValue("day", new DateOnly(2026, 3, 4));
context.SetValue("opening", new TimeOnly(13, 0));
{{ starts }}                                → 2026-03-04 13:00:00 -0500
{{ starts | date: '%Y-%m-%d %H:%M %z' }}    → 2026-03-04 13:00 -0500
{{ starts | time_zone: 'Europe/Berlin' | date: '%H:%M' }} → 19:00
{{ day }}                                   → 2026-03-04
{{ day | date: '%Y-%m-%d %H:%M %z' }}       → 2026-03-04 00:00 +0000
{{ opening }}                               → 13:00:00
{{ opening | date: '%H:%M %z' }}            → 13:00 -0500 (-0400 in summer)
  • A DateTime is like a Ruby Time created in the time zone of the context: it renders like Time#to_s, with the offset of the context's time zone at that date.
  • A DateOnly is like a Ruby Date, which has no time zone: it renders 2026-03-04, and the date filters read it at midnight UTC, so {{ day | date: '%s' }} is the same whatever the time zone.
  • A TimeOnly has no Ruby equivalent. It renders 13:00:00, and is read on the current date of the context, TemplateContext.Now() in its time zone, like Ruby's Time.parse("13:00"), so its offset follows daylight saving time.
  • Like in Ruby, a time that the clocks skip when daylight saving time starts is read at the offset before the change and shown at the offset after it: 2026-03-08 02:30 in New York is 2026-03-08 03:30:00 -0400. A time that exists twice when daylight saving time ends is read at the standard offset: 2026-11-01 01:30 is -0500. Date strings without an offset are read the same way.
  • json writes them as "2026-03-04T13:00:00", "2026-03-04" and "13:00:00".
  • In .NET, ToObjectValue() returns the DateTime, DateOnly or TimeOnly.

A DateTime of Utc or Local kind is a moment, a DateTimeValue: a Utc one keeps the +00:00 offset and a Local one, like DateTime.Now, the offset of the machine. The context's time zone doesn't change them.

Breaking changes:

  • A DateTime of Unspecified kind was read in the time zone of the machine, ignoring the options and the context: 13:00 was formatted as 13:00 +0100 on a server in Paris whatever TemplateContext.TimeZone was, and rendered in UTC as 2026-03-04 12:00:00Z. ToObjectValue() returned a DateTimeOffset.
  • A DateOnly was converted to a string with the culture of the options, 03/04/2026 with the invariant culture, which the date filters read as April 3 in the time zone of the context.
  • A TimeOnly was converted to a string like 13:00.
  • A date was its number of .NET ticks in math filters: {{ starts | plus: 0 }} rendered 639082260000000000, and now renders 0 like in Liquid.
  • A number with a fraction was read as a timestamp to the millisecond: {{ 0.5 | date: '%L' }} rendered 500. Like in Liquid, only an integer is a timestamp now, and date returns 0.5 unchanged.

DateTimeValue.Create(DateTime) is unchanged and still reads an Unspecified DateTime in the time zone of the machine: use PlainDateTimeValue.Create() in value converters.

Comparing DatesLink to this heading

Like a Ruby Time or Date in Liquid, dates are ordered: <, <=, > and >= compare two moments (DateTime and DateTimeOffset values) or two DateOnly values chronologically, and sort sorts them chronologically. Moments are compared as instants, whatever their offset. Like in Ruby, comparing a moment with a DateOnly, a string or a number fails, like comparison of Time with Date failed, and comparing a DateOnly with a number compares its astronomical Julian day. Two TimeOnly values, or two TimeSpan values, are ordered too, by time of day or duration: {% if opens < closes %}. They have no Ruby equivalent, so like an object in Liquid, comparing one with any other kind of value is false.

{% if published < expires %}...{% endif %}
{{ articles | sort: 'published' | map: 'title' | join: ', ' }}

Breaking change: comparing dates was always false, and sort sorted them as text.

Date MathLink to this heading

Like in Liquid, a date isn't a number: it is 0 in math filters like plus or minus, whatever its type. Do the math on its Unix time instead, which date: '%s' returns, and read the result with date in the time zone of the context:

{{ starts | date: '%s' | plus: 86400 | date: '%Y-%m-%d %H:%M' }}  → 2026-03-05 13:00
{% assign from = day | date: '%s' %}
{{ '2026-12-25' | date: '%s' | minus: from | divided_by: 86400 }} → 296

Adding 86400 adds 24 hours, which is a different clock time on the day daylight saving time starts or ends.

Time SpansLink to this heading

A TimeSpan is a time of day or a duration, not a moment, so it has no time zone of its own. It renders in its constant format, like 13:00:00 or 1.02:00:00 for 26 hours:

var context = new TemplateContext
{
    TimeZone = TimeZoneInfo.FindSystemTimeZoneById("America/New_York")
};

context.SetValue("opening", TimeSpan.FromHours(13));
{{ opening }}                              → 13:00:00
{{ opening | date: '%H:%M %z' }}           → 13:00 -0500
{{ opening | format_date: 'HH:mm K' }}     → 13:00 -05:00
{{ opening | time_zone: 'Europe/Berlin' | date: '%H:%M' }} → 19:00

The date filters (date, format_date and time_zone) read it as that time on January 1, 1970, at the standard offset of the context's time zone, so the clock time is kept whatever the time zone. Since a time of day isn't a moment, the offset is the one the time zone has today without daylight saving time, not the one it had in 1970: +03:00 in Istanbul, +10:00 in Sydney. Like in Liquid, where only numbers and strings are numbers, it is 0 in math filters such as plus: to do math on a duration, put its TotalSeconds or TotalMinutes in the model. In .NET, ToObjectValue() returns the TimeSpan.

Breaking change: Fluid used to convert a TimeSpan to the moment this long after 1970-01-01 00:00 UTC, in the time zone of the options, ignoring TemplateContext.TimeZone. It rendered like 1970-01-01 13:00:00Z, ToObjectValue() returned a DateTimeOffset, 13:00 was formatted as 08:00 -05:00 in New York, and it was its number of .NET ticks in math filters.

The TimeZone PropertyLink to this heading

The TimeZone property is available in both TemplateOptions and TemplateContext:

// Set globally for all templates using these options
var options = new TemplateOptionsBuilder()
    .WithTimeZone(TimeZoneInfo.FindSystemTimeZoneById("Pacific Standard Time"))
    .Build();

// Or set per template context
var context = new TemplateContext
{
    TimeZone = TimeZoneInfo.FindSystemTimeZoneById("America/New_York")
};

Use Cases for the TimeZone Property:

  • Parsing date strings without explicit time zone information
  • Reading dates and times without a time zone: DateTime values of Unspecified kind, DateOnly, TimeOnly and TimeSpan
  • Showing the current time: like Ruby's Time.now, 'now' and 'today' are the instant TemplateContext.Now() returns, in this time zone, whatever the offset Now has (the machine's one by default). With the time zone set to New York, {{ 'now' | date: '%H:%M %z' }} renders the time in New York, like 13:00 -0500.
  • Ensuring consistent date parsing across different server environments
  • Interpreting user input in a specific time zone

Breaking change: 'now' and 'today' used to keep the offset of TemplateContext.Now(), so they showed the machine's time (or UTC with WithNow(() => DateTimeOffset.UtcNow)) whatever the time zone. The instant, {{ 'now' | date: '%s' }}, is the same.

What it Does NOT Do:

  • Automatically convert DateTime values during rendering
  • Change the time zone of DateTime objects in your model
  • Apply to dates that already have time zone information

Converting Time Zones During RenderingLink to this heading

To display dates in a specific time zone, use the time_zone filter:

Using the time_zone FilterLink to this heading

The time_zone filter converts a DateTime to a specific time zone:

{{ BirthDate | time_zone: 'America/New_York' | date: '%+' }}

The 'local' KeywordLink to this heading

The special keyword 'local' converts to the context's configured time zone:

var context = new TemplateContext(data, new TemplateOptionsBuilder()
    .WithTimeZone(TimeZoneInfo.FindSystemTimeZoneById("Europe/Uzhgorod"))
    .Build());
{{ BirthDate | time_zone: 'local' | date: '%c' }}

This will convert BirthDate to the "Europe/Uzhgorod" time zone before formatting it.

Important: Use the date filter to choose how the converted date is formatted. Without it, the date renders like a Ruby Time, with the offset of the time zone it was converted to: 2022-02-02 14:00:00 +0200.

Complete ExampleLink to this heading

Here's a complete example showing the difference:

using Fluid;

const string text = @"
Without conversion: {{ BirthDate }}
With time_zone filter: {{ BirthDate | time_zone: 'local' | date: '%c' }}
Explicit timezone: {{ BirthDate | time_zone: 'Europe/Uzhgorod' | date: '%c' }}
";

var date = new DateTime(2022, 2, 2, 12, 0, 0, DateTimeKind.Utc);
var timezone = TimeZoneInfo.FindSystemTimeZoneById("Europe/Uzhgorod");

var data = new
{
    BirthDate = date
};

var parser = new FluidParser();
var template = parser.Parse(text);

var context = new TemplateContext(data, new TemplateOptionsBuilder()
    .WithTimeZone(timezone)
    .Build());

var result = template.Render(context);
Console.WriteLine(result);

Output:

Without conversion: 2022-02-02 12:00:00 UTC
With time_zone filter: Wednesday, 02 February 2022 14:00:00
Explicit timezone: Wednesday, 02 February 2022 14:00:00

Notice that the time_zone filter must be combined with the date filter to properly display the converted time. The first line shows the UTC time, while the filtered versions show the time converted to 14:00 in the Uzhgorod timezone (UTC+2).

Resolving Time Zone IdentifiersLink to this heading

On .NET 6 and later, the time_zone filter resolves identifiers with TimeZoneInfo.FindSystemTimeZoneById. Both IANA identifiers such as America/Los_Angeles and Windows identifiers such as Pacific Standard Time are supported across platforms when ICU globalization data is available. Fluid's netstandard2.0 asset uses TimeZoneConverter as its default resolver for compatibility with older runtimes.

var options = new TemplateOptionsBuilder().Build();
var context = new TemplateContext(options);

var template = parser.Parse(
    "{{ published | time_zone: 'America/Los_Angeles' | date: '%+' }}");

IANA identifiers are not available through TimeZoneInfo on Windows when globalization invariant mode or NLS mode is enabled. You can replace the resolver through TemplateOptionsBuilder.WithTimeZoneResolver(). For example, an application using the TimeZoneConverter package can configure:

using TimeZoneConverter;

var options = new TemplateOptionsBuilder()
    .WithTimeZoneResolver(id => TZConvert.GetTimeZoneInfo(id))
    .Build();

var context = new TemplateContext(options);

The resolver is used for explicit identifiers passed to the time_zone filter. The special local identifier still uses TemplateContext.TimeZone.

Automatic Conversion with Value ConvertersLink to this heading

If you want to automatically convert all DateTime values to a specific time zone without using the time_zone filter everywhere, you can use a value converter:

Creating a Time Zone Value ConverterLink to this heading

using Fluid;
using Fluid.Values;

var timeZone = TimeZoneInfo.FindSystemTimeZoneById("Europe/Uzhgorod");

// Add a value converter that automatically converts all DateTime values
var options = new TemplateOptionsBuilder()
    .WithTimeZone(timeZone)
    .AddValueConverter(obj =>
    {
        // A DateTime of Unspecified kind has no time zone to convert from, Fluid reads it in the context's one.
        if (obj is DateTime dt && dt.Kind != DateTimeKind.Unspecified)
        {
            // Convert to the options' time zone
            var converted = TimeZoneInfo.ConvertTime(new DateTimeOffset(dt), timeZone);
            return DateTimeValue.Create(converted);
        }

        if (obj is DateTimeOffset dto)
        {
            // Convert to the options' time zone
            var converted = TimeZoneInfo.ConvertTime(dto, timeZone);
            return DateTimeValue.Create(converted);
        }

        return null; // No conversion needed
    })
    .Build();

var data = new
{
    BirthDate = new DateTime(2022, 2, 2, 12, 0, 0, DateTimeKind.Utc)
};

var context = new TemplateContext(data, options);

Now all DateTime values will be automatically converted to the configured time zone. To see the converted time in your output, use the date filter:

{{ BirthDate | date: '%c' }}

Output: Wednesday, 02 February 2022 14:00:00 (converted to Europe/Uzhgorod time zone, UTC+2)

Note: Without a format filter (e.g., {{ BirthDate }}), a date renders like a Ruby Time, with its offset: 2022-02-02 14:00:00 +0200 here. Use the date filter with a format string to choose the format.

Advantages of Value ConvertersLink to this heading

  • Centralized time zone conversion logic
  • Automatic conversion of all dates in your models
  • No need to remember to use time_zone filter on every date (though you still need the date filter for formatted output)

Disadvantages of Value ConvertersLink to this heading

  • Less flexibility - all dates are converted the same way
  • May not be appropriate if you need different time zones for different dates
  • Less explicit - the conversion happens behind the scenes
  • Still requires using the date filter to see timezone-aware formatted output

Common Patterns and ExamplesLink to this heading

Pattern 1: Display Server Time in User's Time ZoneLink to this heading

// In your application setup
// Add a converter to display all dates in the user's time zone
var options = new TemplateOptionsBuilder()
    .AddValueConverter(obj =>
    {
        if (obj is DateTime dt && dt.Kind == DateTimeKind.Utc)
        {
            // This would typically come from user preferences
            var userTimeZone = TimeZoneInfo.FindSystemTimeZoneById("America/Los_Angeles");
            var converted = TimeZoneInfo.ConvertTime(dt, userTimeZone);
            return DateTimeValue.Create(converted);
        }
        return null;
    })
    .Build();

Template:

Server time: {{ ServerTime }}

Pattern 2: Display Multiple Time ZonesLink to this heading

UTC: {{ EventTime }}
New York: {{ EventTime | time_zone: 'America/New_York' | date: '%c' }}
London: {{ EventTime | time_zone: 'Europe/London' | date: '%c' }}
Tokyo: {{ EventTime | time_zone: 'Asia/Tokyo' | date: '%c' }}

Pattern 3: User-Specific Time ZoneLink to this heading

var context = new TemplateContext(model, options);

// Set the user's preferred time zone
context.TimeZone = userPreferredTimeZone;

Template:

Your local time: {{ EventTime | time_zone: 'local' | date: '%c' }}

Pattern 4: Parsing User InputLink to this heading

var context = new TemplateContext
{
    // User is entering times in Pacific time
    TimeZone = TimeZoneInfo.FindSystemTimeZoneById("America/Los_Angeles")
};

Template (parsing a user-entered date):

{% assign meeting_time = '2024-03-15 14:30' | date: '%+' %}
Meeting scheduled for: {{ meeting_time }}

The date string will be interpreted as Pacific time, not UTC.

Time Zone IdentifiersLink to this heading

Fluid uses TimeZoneInfo on .NET 6 and later and TimeZoneConverter on netstandard2.0. The default resolver supports:

  • IANA time zone IDs (e.g., "America/New_York", "Europe/London")
  • Windows time zone IDs (e.g., "Pacific Standard Time", "GMT Standard Time")
  • Cross-platform resolution on .NET 6 and later when ICU globalization data is available

Use TemplateOptionsBuilder.WithTimeZoneResolver() when your runtime does not provide the identifiers your templates need.

Finding Time Zone IDsLink to this heading

IANA IDs (recommended for cross-platform apps):

"America/New_York"    // Eastern Time
"America/Los_Angeles" // Pacific Time
"Europe/London"       // British Time
"Asia/Tokyo"          // Japan Time
"UTC"                 // Coordinated Universal Time

Windows IDs:

"Eastern Standard Time"
"Pacific Standard Time"
"GMT Standard Time"
"Tokyo Standard Time"

You can get a list of all available time zones:

foreach (var tz in TimeZoneInfo.GetSystemTimeZones())
{
    Console.WriteLine($"{tz.Id}: {tz.DisplayName}");
}

SummaryLink to this heading

Scenario Solution
Parse date strings without time zone info Set TemplateContext.TimeZone
Format a TimeSpan as a time of day Use the date or format_date filter, in the context's time zone
Read DateOnly, TimeOnly and Unspecified DateTime values in a time zone Set TemplateContext.TimeZone, the machine's one is never used
Display dates in a specific time zone Use {{ date \| time_zone: 'timezone-id' }} filter
Display dates in the context's time zone Use {{ date \| time_zone: 'local' }} filter
Resolve identifiers with a custom library Set TemplateOptionsBuilder.WithTimeZoneResolver()
Automatically convert all dates Use a ValueConverter
Display dates in multiple time zones Use multiple time_zone filters with different IDs

Additional ResourcesLink to this heading

Esc to close