I've been using @media queries in CSS forever, but on a number of occasions these type of Viewport-only limits on width are problematic, especially in UIs that are user resizable or can otherwise dynamically change the sizing of components or panels.

My specific scenario is a resizable panel display where a fixed @media width causes problems due to the container, rather than the window, needs resizing.

Most of us have likely used the @media at-rule for responsive design, but it's limited to the Viewport width.

There's another, more recent type of conditional CSS at-rule that can be used to restrict sizing: @container which I have been unaware of until recently. @container is a relatively new addition to CSS that was only introduced to browsers a few years back in 2022/23, so perhaps I'm not the only one who got caught unawares that this even exists.

Here's are how the two at-rules differ from each other:

• @media
  Works off of min/max values of the ViewPort of the host frame.
  more info

• @container
  Allows specifying of a Parent Container Name to apply the min/max values to.
  more info

The Problems with @media Queries

@media queries are great, when you're dealing with page wide content. If your page consists of a single host container that doesn't change, using @media queries works perfectly fine and it's a staple of Responsive and Mobile First Design. Especially in Mobile layouts that tend to be relatively simple single pane layouts @media constraints are just fine.

But... if you have multiple content panes in your page, or resizable or movable ones at that, @media queries can be too broad of a brush to apply to get the result you need to control nested container content.

For reference @media queries look like this:

.topic-outline {
    display: none;
}

@media(min-width: 1100px){ 
    .topic-outline {
        position: fixed;
        display: block;
        overflow-y: auto;

        top: 7em;
        right: 1em;
        max-height: calc(100vh - 10em);
        width: 255px;

        font-size: 0.725em !important;
        line-height: 1.4em;

        margin-top: 0px;
        margin-left: 10px;
        padding: 20px 3px 0 20px;
    }
}    

The @media(min-width: 1100px) { } block contains a subset of CSS that is applied when the condition is true - in this case if the Viewport width exceeds a minimum of 1100px.

The above CSS is from a specific example from one of my documentation Web sites generated with Documentation Monster, which originally used @media queries in its topic templates used for rendering topics. DM renders the final output into a two-pane view that contains a table of contents on the left and a resizable content pane on the right with a splitter in the middle. The content pane then conditionally displays a left hand sidebar that shows a document outline if the pane is large enough.

The following screen capture demonstrates some of the problems with @media only queries. Keep an eye on the bookmark sidebar ("On this page:") on the right. The intent is that as the content panel gets smaller than a certain size, the bookmark toolbar disappears and reappears as the width expands.

Figure 1 - Using @media queries allows sizing per window, which can cause problems if you have resizable content that needs to conditionally render or modify content. Here you can see some inconsistent behavior for the bookmarks sidebar and content pane when then content pane is resized.

If you look closely you can see that the initial full window resizes work properly with the sidebar showing and hiding as expected.

However, resizing with the splitter from a size where the bookmark sidebar shows, to a size where it should hide, you can see the sidebar causing the content to get crunched, rather than hiding the sidebar and allowing the content to flow wider which is the expected and designed behavior. It works with Window resizing but fails with container resizing. Similar behavior shows with the hamburger menu that is showing and hiding the TOC.

This example uses the @media at-rule, and it's misbehaving because the sizing condition is based on window sizing, not container sizing. The result is that in some instances you don't get the right behavior of the sidebar showing or hiding as it should.

Fixing this is not possible with @media queries alone, because it only works as expected when the entire window size changes.

Note that in this scenario the @media query also misrepresents the intent of the size restriction. Specifically in Documentation Monster there's a preview that uses the same HTML but always hides the TOC on the left. So right of the start the @media query sizing in that scenario is off by the 350px or so of the TOC panel. IOW the intent of the sizing here is clearly on the container, not the window, but a @media query alone doesn't really address that. There are ways around that with extra CSS class definitions but that gets messy quick as you have to duplicate many CSS attributes.

@container Queries

The @container at-rule fixes this by explicitly allowing you to specify a container to restrict by for the query condition. So rather than being tied to the window, a @container query is scoped to a specific container.

To get back to the Documentation example shown above here's is the example behaving correctly with the @container query:

Figure 2 - Using @container queries allows more control by selecting a specific container to apply a media query to. Here you can see the bookmarks sidebar correctly diplaying depending on the content container only.

Notice that now, using the slider or hamburger menu correctly shows and hides the bookmark sidebar as the the sizing is now dependent on the size of the content pane, rather than the size of the window.

Yay.

@container Syntax: A two-step Process

To use the @container at-rule in the same way as the @media query above, is a two part process:

• Setting a container-name in the parent CSS Class
  The parent container which is targeted by @container needs to be explicitly defined in the CSS with something like container-name: main-content to be used as a parent in a @container query.

• Applying the @container at-rule
  Once a container has been defined with container-name you can then use it with:

  @container main-content (min-width: 1100px) { /* css styles */  }
  

  The behavior otherwise is identical to a @media query block including the same min-width/max-width rules.

A Space after the Name is Required!

When I originally found out about , I made the mistake of writing it @container main-content(min-width: 1100px). Notice no space between the name and the () query condition and that did not work. And yes I spent 20 minutes cursing that this feature doesn't work, only to have an agent slap me in the face with the space requirement 😄. So:

The space after the name is absolutely required!

@container main-content (min-width: 1100px)
                       ^

No Container Name works too, but...

Actually, the container-name and specification in the @container are not absolutely required. If you don't specify one, the eligible ancestor query container(s) of the style(s) in the CSS block are used for the container it's applied to. So essentially the parent element(s) of each of the styles represented.

This can be pretty arbitrary, and because of that I personally prefer to be explicit and provide a specific container via container-name.

So in this CSS:

@container (width > 920px) {
    .topic-outline {
        display: block;
    }

    .content-pane {
        margin-right: 235px;
    }

    .footer {
        font-size: 0.9rem;
    }
}

Each style's parent container is considered rather than a single container. As you might imagine this can get confusing quickly.

If you don't use a container-name I'd make sure to stick to embedding a single style or at least any styles that have the same parent. Alternately if you want to control several elements, create a new CSS class and apply the container-name to it, then assign the class to all affected elements to be explicit. This avoids confusing and hard to debug scenarios later on.

Applying the @container at-rule

Let's break down the full syntax:

Start by setting a container-name in the container element that the resizing should be based on. I'm using an #id here, but you can point at any CSS selector:

#MainContent {
    container-name: main-content;
    container-type: inline-size;
}

In my case I have an explicit Id for the content container so I used that. If you don't have an explicit CSS style defined that matches your container exactly, you need to create one and add container-name.

Once you have container-name defined in your CSS, you can then reference the it in the @container directive:

@container main-content (min-width: 920px){
   .topic-outline {
       position: fixed;
       display: block;
       overflow-y: auto;

       top: 7em;
       right: 1em;
       max-height: calc(100vh - 10em);
       width: 255px;

       font-size: 0.725em !important;
       line-height: 1.4em;

       margin-top: 0px;
       margin-left: 10px;
       padding: 20px 3px 0 20px;
   }
@container main-content (min-width: 1100px) {
        .topic-outline {
            width: 400px;
            font-size: 0.725em !important;
        }
        .content-pane.topic-outline-visible {
            margin-right: 380px;
        }
    }
}   

And that's it!

Summary

CSS @container queries provide a much-needed solution for container-level responsive design where viewport-based @media queries fall short.

With a few very minor changes to the CSS, I've resolved a very long running nagging CSS issue, that I put up with for a long time. At its original inception this issue had no quick resolution because @container didn't exist at the time other than resorting to script code.

But now, with this relatively new @container feature I get the intended behavior with minimal effort and a very simple change path from the original behavior. Nice!

@container was new to me since it is a relatively new at-rule, so it might be new to you too, so I hope this is useful to some of you...

Resources

• @container MDN Documentation
• @media MDN Documentation

this post was created and published with the Markdown Monster Editor

In many of my Web applications I have a few files that are dynamically created as part of administrative tasks. These files tend to be cumulative and contain data that can be accessed directly from the file system. But... they are in effect static files, but they shouldn't be accessible by just anybody. They should still respect authentication rules.

For example, in several small apps I write application error logs into /wwwroot/admin/temp. In another application that does occasional order processing, I track processing errors in files in a similar manner.

But again - these files can potentially contain sensitive information so they shouldn't be accessible by just any user, but only by logged in Admin users or whatever elevated group of users has access to that type of information.

What exactly does wwwroot do?

The wwwroot folder in your project is the 'static files' folder for your ASP.NET Web application. As the name suggests it assumes static content that doesn't change.

wwwroot is a ASP.NET Project Thang

The way it works is that in your ASP.NET projects anything that you store in the wwwroot folder is mapped into the Web root of the published Web site so that a /wwwroot/somefile.html file maps to /somefile.html on your published Web site.

It's also possible to publish sites into subfolders or virtual folders/sites/applications (on IIS) in which case wwwroot maps to /subfolder/somefile.html.

• Running ASP.NET Core Applications as a Subfolder Application

The key here is that by default (if you don't mess with the property publish settings) all files in the wwwroot folder are published to the Web root on the publish site.

Static File Middleware

In order for static files to be actually served by ASP.NET you need to add the StaticFiles middleware in your app's startup code in program.cs:

app.UseStaticFiles()

The middleware handles the actual semantics of translating paths into static files, and also provides a host of features like virtualization of file providers, content compression and caching.

By default everything in the wwwroot folder is published and then served as public by the middleware and directly accessible by anybody browsing your site. ASP.NET doesn't restrict access to static content by default.

In most cases that's exactly what you want. Static content mostly consists of support resources for your project:

• Images
• CSS
• JavaScript
• Static Html
• Media content
• Downloadable files

and in most cases that content should be directly accessible without any authentication or other restrictions beyond site level security.

The static file middleware is not limited to what you publish in your wwwroot folder. Anything else you manually copy into the Web Root folder or dynamically create and then store there is also accessible. The default file provider points at a folder and serves all files in and below that folder.

Static Files Middleware can do More!

The default use case for the static files middleware is to serve root Web folder content from published wwwroot output, but you can use this middleware for many different scenarios by using alternate or customized the file providers (IFileProvider). For starters, you can point at a different folder than wwwroot or point at multiple folders to serve static files from, which is particularly useful for serving application specific resources that are stored separately from the Web app.

There are several different types of file stores that can be used to serve files from Resources, Azure etc. and you can implement your own IFileProvider implementations that serve from different sources.

Protecting Folders or Files in wwwroot

But... in some cases you do need to protect dynamically created files that are served as static content. Technically that's not static content, since it was generated, but it lives in the scope of the Static File middleware.

There's no 'built-in' way to secure static files served from the StaticFile middleware. If the middleware fires, the files get served.

So in order to limit access a separate approach is required that explicitly prohibits access to specific paths.

There are a few ways to do this, none of them particularly clean:

• Move files outside of wwwroot
  One thing that can be done is move files out of wwwroot and then explicitly have endpoints that either map individual files or wildcard catch-all routes for files.

• Use endpoint-routing with Catch All route You can send minimal API routes or controller routes with catch-all route parameters ({*path} or {**path}) that give you the remaining path of the Url.

• Use custom middleware Similarly you can create a generic Middleware handler that looks at all requests and explicitly filter out requests.

StaticFileOptions.OnPrepareResponse is sometimes suggested for this job, but I don't like it as an authorization boundary. That callback runs after the static-file middleware has already selected a file and prepared the response. It's useful for setting headers, but rejecting the request before static-file processing is easier to reason about.

There are other approaches I've seen suggested using custom Authorization policies and complex routing setups, but that all seems insanely complex for what is essentially a relatively simple task.

The simplest thing seems to be, intercepting the request either with a generic middleware handler, or a catch all route. Both of these use essentially the same concept of looking at the Url and deciding whether requests can go through or not - and if not forcing a login (or at least a 401 result).

My personal preference is the custom middleware which I'll describe below.

Use Custom Middleware

For an existing application that already writes files below wwwroot, the least disruptive solution is often a small generic middleware handler that examines the request path and explicitly rejects requests that aren't authorized.

Here's the relevant part of my application setup which requires authentication for any file requests comes out of an /admin folder:

app.UseRouting();

// Authentication has to run before checking ctx.User
app.UseAuthentication();

// Protect everything below /admin, including static files
// has to run before the static files middleware
app.Use(async (ctx, next) =>
{
    if (ctx.Request.Path.StartsWithSegments(
            "/admin", StringComparison.OrdinalIgnoreCase))
    {
        if (ctx.User.Identity?.IsAuthenticated != true)
        {
            ctx.Response.StatusCode = StatusCodes.Status401Unauthorized;
            await ctx.Response.WriteAsync("401 Unauthorized");
            return;
        }

        // Retrieve application user state from claims and validate access
        var userState = UserState.CreateUserState<WebStoreAppUserState>(ctx);
        if (!userState.IsAdmin)
        {
            ctx.Response.StatusCode = StatusCodes.Status403Forbidden;
            await ctx.Response.WriteAsync("403 Forbidden");
            return;
        }
    }

    await next();
});

// Static files are served only after the /admin check
app.UseStaticFiles();

app.UseAuthorization();

The two return statements are important: denied requests must short-circuit the middleware pipeline. Setting a status code and then calling next() still allows the static-file middleware to process the request.

I'm using application-specific UserState code here, but you can replace that check with ctx.User.IsInRole("Admin"), a claim check, or whatever authorization logic your application uses.

StartsWithSegments() also matters. A string test such as Contains("/admin/") can match unintended URLs and misses the exact /admin path. Segment matching clearly scopes the check to /admin and everything below it.

Finally, middleware order is critical:

• UseAuthentication() has to run before the custom check so that ctx.User is available for my check scenario.
• The custom check has to run before UseStaticFiles() so a rejected request never reaches static-file handling.
• If a front-end Web server serves the file directly, none of this code runs. More on that shortly.

Why MapGet() Doesn't Intercept the File

A similar approach is to use minimal APIs or a controller endpoint with a catch-all route. For minimal APIs you can use a catch-all MapGet() handler such as app.MapGet("/admin/{**path}").

Single vs Double Asterisk Catch-All Parameters

Catch-all routing parameters can use either one or two asterisks: {*path} or {**path}. Both match the remaining part of a URL, including slashes and other characters, and can also match an empty string.

The single-asterisk version URL-encodes forward slashes when generating a URL, while the double-asterisk version preserves them.

Unfortunately, in my application, which uses controller routing and static-file middleware, the MapGet() handler never fired for an existing static file.

The following did not intercept the request:

app.MapGet("/admin/{**path}", async (HttpContext ctx, string path) =>
{
  return "Path: " + path;
});

app.UseStaticFiles();
app.UseRouting();

This isn't really a route-priority problem. Static-file middleware handles a matching file and short-circuits the pipeline before the mapped endpoint executes. Moving declarations around in a Minimal API application's compact startup code can make this behavior less than obvious because route registration and middleware execution aren't the same thing.

You can make endpoint routing work by explicitly arranging the pipeline, or by having the endpoint serve the file itself. But for guarding an existing UseStaticFiles() setup, I find the slightly lower-level app.Use() handler more obvious and unambiguous.

In .NET 9 and later, MapStaticAssets() exposes static assets as endpoints and authorization metadata can be attached to those endpoints. That's useful for build-time application assets, but my files are generated at runtime and only one folder needs protection, so the small middleware check remains a better fit here.

But given the possibility of routing conflicts with .MapGet() or even an explicit route, I'm weary of using that in the future and just opt for the simpler solution of using a generic middleware handler with app.Use() as shown above. It's clear and straight forward and there's no second guessing on when it fires other than pipeline order.

Watch out for your Hosting Platform

Here's another gotcha you may have to watch for:

If you're running your ASP.NET Core application behind a Web server proxy, be aware that the server may be configured to serve static resources directly, effectively bypassing ASP.NET Core processing entirely!

Many of my Web applications still run on a self-hosted IIS VPSs.

In all of my IIS hosted apps I forward most common static file types directly through IIS because it's considerably faster than running them through the ASP.NET Core pipeline, and IIS provides automatic and highly efficient compression for text-based files:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
	<location path="." inheritInChildApplications="false">
		<system.webServer>
            <handlers>
                <!-- Watch out for this one if you're protecting HTML files! -->
                <add name="StaticFileModuleHtml" path="*.htm*" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />

				<add name="StaticFileModuleSvg" path="*.svg" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleJs" path="*.js" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleCss" path="*.css" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleJpeg" path="*.jpeg" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleJpg" path="*.jpg" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModulePng" path="*.png" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleGif" path="*.gif" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleWoff2" path="*.woff2" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
				<add name="StaticFileModuleWoff" path="*.woff" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" />

				<!-- Everything else goes into Kestrel -->
				<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
			</handlers>
		</system.webServer>
	</location>
</configuration>

If you do this and have a mapping for an affected extension (like *.htm* in this case for example), IIS serves the matching file without forwarding the request to Kestrel. Your entire ASP.NET Core pipeline, including authentication and the low-level middleware check, never fires. Everything discussed above is completely bypassed.

In my case this doesn't matter because the files I'm concerned about tend to use .txt or .log extensions, which I don't forward through IIS. But if you need to protect HTML documents, for example, you have to remove the path="*.htm*" handler so those requests reach ASP.NET Core and the authorization check can fire or add a special <location> sub-section that explicitly excludes the files from IIS processing.

On the flip side it's also possible to explicitly set file or folder permissions to block access to files using <location> element. However, the auth mechanism used is then outside of the ASP.NET application (Windows Auth?) which is at best... hokey. But for a quick fix if you find out you have a file that needs protecting immediately, that might do the trick.

The same warning applies to CDNs, reverse proxies and container ingress configurations that can serve files without reaching the application. Always test the request through the actual production hosting path, not just against local debug environment which always hits Kestrel.

Summary

By default, ASP.NET Core serves all content within the wwwroot directory as public static assets without authorization checks. When applications write sensitive or dynamically generated files (such as error logs or admin reports) into wwwroot, access needs to be restricted.

The most straightforward approach described in this post, is to insert a lightweight custom middleware into the pipeline to explicitly reject requests that are not authenticated. In order to do this it's important to get the order of middleware right so that the checks occur before static files are served but after authentication has provided the necessary user context to decide whether requests can proceed or not.

Officially there are quite a few approaches that can be used but personally I prefer this much more simple and explicit approach to using code to examine path and auth to accept or reject requests, vs complex authorization policies or complex routing order schemes that are often mentioned.

Resources

• Serve static files in ASP.NET Core apps
• Running ASP.NET Core Applications as a Subfolder Application

this post was created and published with the Markdown Monster Editor

Classic native Date values in JavaScript are internally represented as UTC dates. However, when you display values they are by default shown as local date/time values. I've run into this recently again with an application that was returning a mix of UTC and non-UTC dates from the server to the browser, causing some confusion. At that point I realized I was being inconsistent with my use of the my date display functions, and here I am reviewing various Date formatting and Date conversion operations.

JavaScript's core behavior is consistent once you separate two different concepts:

• The instant represented by a Date
• The timezone used to display that instant

An instant is essentially an instant in time expressed in an offset since the Unix Epoch:

January 1, 1970 00:00:00 UTC

The instant is represented via new Date().getTime() or a more precise value of Temporal.Instant which represents the unique point in time, with nanosecond precision. It is fundamentally represented as the number of nanoseconds since the Unix epoch (midnight at the beginning of January 1, 1970, UTC), without any time zone or calendar system.

The most common usage of dates is via the Date object and its methods. Dates are stored as UTC values, but standard display of dates in the browser UI or via the debug tools shows dates in local time.

So when you output a date it looks like this (PST or America/Los Angeles timezone in this case):

new Date()
// Mon Aug 24 2026 11:33:26 GMT-0700 (Pacific Daylight Time)

my current PST timezone value is displayed with toString() or any string concat operation. Notice that the date formatter automatically adjusts for Daylight savings time of the active timezone.

I also get a time adjusted value, if I explicitly convert the value using toLocaleTimeString() which gives me just the time value as a string:

new Date().toLocaleTimeString()
// '11:33:46 AM'

I can also go the other way - if I want to actually display the UTC value I can use the following:

new Date().toLocaleTimeString(undefined, { timeZone: "UTC" });
'6:33:43 PM'

I can also specify any specific defined timezone using the familiar timezone abbreviations:

new Date().toLocaleTimeString(undefined, { timeZone: "EST" });
// '1:34:02 PM'

or using a full IANA Time Zones identifier:

new Date().toLocaleTimeString(undefined, { timeZone: "America/New_York" });
// '1:34:02 PM'

Get your Local Timezone

If you're like me you're probably used to seeing timezone values represented by their shortcut names like PST, EST, CET etc., but officially JavaScript uses IANA Time Zones which are represented like America/Los_Angeles, Pacific/Honolulu, Europe/Berlin etc. There are actually many overlapping formats such as Pacific/Honolulu, US/Hawaii and HST for my Hawaii timezone that all represent the same UTC -10 timezone.

I'm in Hood River (near Portland, OR) currently, but the active PST timezone that gets returned is America/Los_Angeles, which seems semantically very wrong, but does represent the correct UTC -8 timezone.

You can find out the local timezone like this:

Intl.DateTimeFormat(undefined, { timeZoneName: "short" })
   .resolvedOptions().timeZone;
// 'America/Los_Angeles'

or for the abbreviation.

new Intl.DateTimeFormat(undefined, { timeZoneName: "short" })
.formatToParts(new Date())
.find(x => x.type === "timeZoneName")?.value;
// PDT

Dates are Instants, Display is Local

The most important thing to keep in mind is this:

const date = new Date("2026-08-24T18:33:46.000Z");

date.toISOString();
// '2026-08-24T18:33:46.000Z'

date.toString();
// 'Mon Aug 24 2026 11:33:46 GMT-0700 (Pacific Daylight Time)'

toISOString() returns the instance UTC value with no date time offset regardless of whether the instance has a timezone or not ie. 2026-08-24T18:33:46.000Z. The Z at the end indicates the UTC timezone.

toString() and most other date output functions return local time values adjusted for the current timezone.

This is where JavaScript can be confusing because many Date methods are split between local-time and UTC-time versions:

const date = new Date("2026-08-24T18:33:46.000Z");

date.getHours();
// 11   local time for me

date.getUTCHours();
// 18   UTC time

Yeah that .getHours() value is confusing if the time instance is a UTC value, but the bottom line is that any of the 'standard' date operations use local dates unless you explicitly use the UTC or ISO functions.

Formatting Dates with Intl.DateTimeFormat

You can use toLocaleString() to format dates and times, but if you want more control you can use the Intl.DateTimeFormat object which makes formatting more explicit and reusable.

const formatter = new Intl.DateTimeFormat(undefined, {
	dateStyle: "medium",
	timeStyle: "short"
});

formatter.format(new Date("2026-08-24T18:33:46.000Z"));
// 'Aug 24, 2026, 11:33 AM'  // on my machine

The first parameter of the constructor is the locale ie. en-US or de-DE. Passing undefined use the current user's locale.

To override for a specific timezone you can explicitly specify it as part formatting parameters for timeZone. To explicitly show UTC time:

const utcFormatter = new Intl.DateTimeFormat(undefined, {
	year: "numeric",
	month: "short",
	day: "numeric",
	hour: "numeric",
	minute: "2-digit",
	timeZone: "UTC",
	timeZoneName: "short"
});

utcFormatter.format(new Date("2026-08-24T18:33:46.000Z"));
// 'Aug 24, 2026, 6:33 PM UTC'

To show a specific user's timezone formatted for a specific locale:

const newYorkFormatter = new Intl.DateTimeFormat("en-US", {
	year: "numeric",
	month: "short",
	day: "numeric",
	hour: "numeric",
	minute: "2-digit",
	timeZone: "America/New_York",
	timeZoneName: "short"
});

newYorkFormatter.format(new Date("2026-08-24T18:33:46.000Z"));
// 'Aug 24, 2026, 2:33 PM EDT'

Serve me this, Client me That

The way that timezone display works in browsers makes sense 99% of the time as you typically want to display the timezone as local in the client browser.

But it gets a lot more complicated when the dates are server rendered or passed from the server to the client via API calls. The issue here is that the dates on the server might be stored for a specific timezone and perhaps are even returned with that timezone information encoded into the JSON payload.

This is why most applications store dates dates as UTC and then adjust the value on the client or on the server based on user preferences configured.

UTC dates are most consistent, but for users displaying a UTC date is definitely not ideal. It might work for logs or other systems related information, but for end users local time or a selected timezone display is a requirement.

For many applications I like the second option for user-facing screens: send the timestamp as UTC or ISO 8601 in the HTML, then let client-side JavaScript render it into the user's actual local timezone - potentially adjusted for a user specified timezone.

For example:

<time datetime="2026-08-24T18:33:46.000Z" class="local-time">
	2026-08-24 18:33 UTC
</time>

and then for browser local time:

const formatter = new Intl.DateTimeFormat(undefined, {
	year: "numeric",
	month: "short",
	day: "numeric",
	hour: "numeric",
	minute: "2-digit",
	timeZoneName: "short"
});

document.querySelectorAll("time.local-time").forEach(element => {
	const date = new Date(element.dateTime);
	element.textContent = formatter.format(date);
});

For a specific timezone you can specify the timezone in the constructor:

let timeZone = userConfig.timeZone;
const formatter = new Intl.DateTimeFormat(undefined, {
	year: "numeric",
	month: "short",
	day: "numeric",
	hour: "numeric",
	minute: "2-digit",
    timeZone: timeZone,  // America/Los Angeles or PST
	timeZoneName: "short"
});

This gives non-JavaScript clients and crawlers a useful UTC fallback, while normal browser users get a local or user specified timezone display value.

Getting the user's TimeZone for the Server

In order for client applications to provide the timezone to the server you can detect the value on the client like this:

Intl.DateTimeFormat().resolvedOptions().timeZone;
// 'America/Los_Angeles'

and then send that to the server. AFAIK the client does not send timezone information to the server as part of browser headers by default, so some explicit API call or similar operation is required to communicate the default to the server.

New JavaScript APIs

The classic JavaScript Date object has been around forever and it's not going away. It works fine for many things, especially if you treat it as an instant and use Intl.DateTimeFormat for display.

But Date is a pretty limited API. It mixes parsing, timestamps, local timezone accessors, UTC accessors, mutable setters, and display helpers into a single object. That's a lot of behavior packed into one small type.

The newish Temporal API

The newer API to keep an eye on is Temporal. Depending on the JavaScript runtime you're targeting you may still need a polyfill, so check current browser and runtime support before using it directly in production code. But conceptually it's a much better model because it separates the things that Date blends together.

The important Temporal types are:

• Temporal.Instant - a point in time, like a better Date timestamp
• Temporal.PlainDate - a calendar date without time or timezone
• Temporal.PlainDateTime - a date and time without timezone
• Temporal.ZonedDateTime - a date and time in a specific timezone

That separation maps much more cleanly to real application data.

For example, an instant displayed in a timezone:

const instant = Temporal.Instant.from("2026-08-24T18:33:46.000Z");

const localTime = instant.toZonedDateTimeISO("America/Los_Angeles");
localTime.toString();
// '2026-08-24T11:33:46-07:00[America/Los_Angeles]'

A plain date that doesn't accidentally roll back a day:

const birthday = Temporal.PlainDate.from("2026-08-24");
birthday.toString();
// '2026-08-24'

And a timezone-aware future event:

const meeting = Temporal.ZonedDateTime.from({
	year: 2026,
	month: 8,
	day: 24,
	hour: 9,
	minute: 0,
	timeZone: "America/New_York"
});

meeting.toInstant().toString();
// '2026-08-24T13:00:00Z'

Even if you don't use Temporal yet, the model is useful: decide whether your value is an instant, a plain date, a local date/time, or a timezone-aware date/time. That decision prevents a lot of downstream confusion.

PlainDate/PlainDateTime is an odd one - it's time instant without any time zone associated with it. It's not UTC, but it's also not specifically tied to any other time zone. These values always print exactly what the values are without any transformation. One example where that's useful is Birthdays, which always are on a certain date and regardless of time zone adjustment stay on that particular date.

Personally I've not used Temporal, yet, but looking at the API I sure can see that it's useful because it allows you to be precise about what type of date you're dealing with. An Instant timestamp, a Plain date or date time value or a timezone specific date and time with the corresponding date formatting string functions to match.

Summary

JavaScript has a fair amount of options for formatting dates and dealing with dates in various time zone formats. The basic Date type is limited to using UTC or local time formats, but using INTL.DateTimeFormat allows you to create specific time instances that can be set to specific timezones which allows you to adjust dates based on user preferences beyond just the default browser time zone.

The Temporal class adds a more specific API for representing Date and Timezone values as a single instance, and goes beyond just displaying timezone adjusted values. I haven't run into a particular use case where this matters, as I typically use UTC dates and only need to display timezone adjusted values, but if you're passing date time values around between different APIs this might be useful.

Resources

• IANA Time Zones
• Intl.DateTimeFormat()
• Temporal
• Temporal.Instance

this post was created and published with the Markdown Monster Editor