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:
- Parsing: When converting strings to DateTime values
- 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_Yorktime zone - The resulting
DateTimeOffsetwill 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
DateTimeis like a RubyTimecreated in the time zone of the context: it renders likeTime#to_s, with the offset of the context's time zone at that date. - A
DateOnlyis like a RubyDate, which has no time zone: it renders2026-03-04, and the date filters read it at midnight UTC, so{{ day | date: '%s' }}is the same whatever the time zone. - A
TimeOnlyhas no Ruby equivalent. It renders13:00:00, and is read on the current date of the context,TemplateContext.Now()in its time zone, like Ruby'sTime.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:30in New York is2026-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:30is-0500. Date strings without an offset are read the same way. jsonwrites them as"2026-03-04T13:00:00","2026-03-04"and"13:00:00".- In .NET,
ToObjectValue()returns theDateTime,DateOnlyorTimeOnly.
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
DateTimeofUnspecifiedkind was read in the time zone of the machine, ignoring the options and the context:13:00was formatted as13:00 +0100on a server in Paris whateverTemplateContext.TimeZonewas, and rendered in UTC as2026-03-04 12:00:00Z.ToObjectValue()returned aDateTimeOffset.- A
DateOnlywas converted to a string with the culture of the options,03/04/2026with the invariant culture, which the date filters read as April 3 in the time zone of the context.- A
TimeOnlywas converted to a string like13:00.- A date was its number of .NET ticks in math filters:
{{ starts | plus: 0 }}rendered639082260000000000, and now renders0like in Liquid.- A number with a fraction was read as a timestamp to the millisecond:
{{ 0.5 | date: '%L' }}rendered500. Like in Liquid, only an integer is a timestamp now, anddatereturns0.5unchanged.
DateTimeValue.Create(DateTime)is unchanged and still reads anUnspecifiedDateTimein the time zone of the machine: usePlainDateTimeValue.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
sortsorted 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
TimeSpanto the moment this long after 1970-01-01 00:00 UTC, in the time zone of the options, ignoringTemplateContext.TimeZone. It rendered like1970-01-01 13:00:00Z,ToObjectValue()returned aDateTimeOffset,13:00was formatted as08:00 -05:00in 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:
DateTimevalues ofUnspecifiedkind,DateOnly,TimeOnlyandTimeSpan - Showing the current time: like Ruby's
Time.now,'now'and'today'are the instantTemplateContext.Now()returns, in this time zone, whatever the offsetNowhas (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, like13: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 ofTemplateContext.Now(), so they showed the machine's time (or UTC withWithNow(() => 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_zonefilter on every date (though you still need thedatefilter 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
datefilter 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
- Ruby date and time format strings - Used by the
datefilter - TimeZoneInfo.FindSystemTimeZoneById - Default time zone resolution
- TimeZoneConverter Library - Optional resolver for additional compatibility
- IANA Time Zone Database - Standard time zone identifiers
- Cultures, dates and time zones - How date strings are parsed
- Adding a value converter - More on value converters