ngx-utc-local-time

UTC ⇄ Local time utilities for TypeScript/Angular — zero dependencies, a clean API, and an Angular pipe for instant use in templates.

• ✅ Zero deps (uses native Date + Intl)
• ✅ Convert UTC ISO → Local (formatted)
• ✅ Convert Local → UTC ISO (reliably for the user’s current time zone)
• ✅ Angular Pipe (utcToLocal) + tiny TimezoneService
• ✅ ESM build with types (CJS optional if you add it)
• ✅ Demo page and Angular playground example

Scope note: This library focuses on converting for the user’s current local time zone (from the browser/Node environment). If you need fully correct conversion across arbitrary IANA zones (e.g., convert “America/Chicago” while the user is in “America/Los_Angeles”), the fallback included here is best-effort. For absolute correctness across DST boundaries for non-local zones, use the Temporal API (if available) or a TZ-database library.

Table of Contents

• Install
• Quick Start
• Angular Usage
• API
• Demo Options
• Why not just new Date()?
• Browser/Runtime Support
• Versioning
• Contributing
• Development
• Publishing (npm + GitHub)
• License

Install

npm i ngx-utc-local-time

Quick Start

TypeScript / Node / Browser (no Angular required): import { fromUtc, toUtc, formatLocal, getUserTimeZone } from "ngx-utc-local-time";

const utcIso = "2025-09-24T18:00:00Z";

// UTC → Local (uses user zone by default) const local = fromUtc(utcIso); console.log(local.formatted); // e.g., "Sep 24, 2025, 11:00 AM" console.log(local.date); // e.g., "2025-09-24" (in your zone) console.log(local.time); // e.g., "11:00 AM"

// Local → UTC (user zone) const iso = toUtc({ date: "2025-09-24", time: "11:00" }); console.log(iso); // "2025-09-24T18:00:00.000Z" (depending on your zone)

// Formatting any Date/ISO as local console.log(formatLocal(utcIso, { dateStyle: "long", timeStyle: "short" }));

// Detect user IANA zone console.log(getUserTimeZone()); // e.g., "America/Los_Angeles"

Angular Usage: Pipe (standalone) // app.module.ts (NgModule) OR standalone bootstrap imports import { UtcToLocalPipe } from "ngx-utc-local-time/angular";

@NgModule({ declarations: [AppComponent], imports: [BrowserModule, UtcToLocalPipe], bootstrap: [AppComponent], }) export class AppModule {}

Component helpers: import { fromUtc, toUtc } from "ngx-utc-local-time";

const r = fromUtc("2025-09-24T18:00:00Z"); // { formatted, date, time, zone, dateObject }

const iso = toUtc({ date: "2025-09-24", time: "11:00" }); // send iso to your backend

API fromUtc(utcIso: string, opts?: FormatOptions)

Converts a UTC ISO string to local presentations.

Returns: API fromUtc(utcIso: string, opts?: FormatOptions)

Converts a UTC ISO string to local presentations.

Returns: { formatted: string; // combined date+time in target zone date: string; // yyyy-mm-dd in target zone time: string; // time-only in target zone (locale-aware) zone: string; // IANA zone used dateObject: Date; // original instant as Date }

FormatOptions: type FormatOptions = { dateStyle?: "full" | "long" | "medium" | "short"; timeStyle?: "full" | "long" | "medium" | "short"; timeZone?: string; // defaults to user's zone seconds?: boolean; // if true, time-only includes seconds locale?: string; // defaults to browser locale }; type FormatOptions = { dateStyle?: "full" | "long" | "medium" | "short"; timeStyle?: "full" | "long" | "medium" | "short"; timeZone?: string; // defaults to user's zone seconds?: boolean; // if true, time-only includes seconds locale?: string; // defaults to browser locale };

toUtc(local: Date | { date: string; time?: string }, opts?: { timeZone?: string })

Converts a local wall-clock value to a UTC ISO string.

When opts.timeZone is omitted, uses the user’s current zone (accurate).

If opts.timeZone differs from the user’s zone, a best-effort conversion is used unless Temporal is available.

Examples: toUtc(new Date()); // now → UTC ISO, using user zone toUtc({ date: "2025-09-24", time: "11:00" }); // → UTC ISO toUtc({ date: "2025-09-24", time: "11:00" }, { timeZone: "America/Chicago" }); // best-effort unless Temporal

formatLocal(input: string | Date, opts?: FormatOptions)

Intl-based formatter that returns a localized string in the chosen zone.

getUserTimeZone(): string

Resolves the IANA zone (e.g., "America/Los_Angeles"), defaults to "UTC" on failure.

Demo Options

1. Static HTML demo

If you pulled the repo/package locally, open: demo/index.html

If you serve it: npx http-server demo -p 5173

visit http://localhost:5173

Angular Playground: Paste this into your app to see it live on http://localhost:4200:

app.component.ts import { Component } from '@angular/core'; import { fromUtc, toUtc } from 'ngx-utc-local-time';

@Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'], }) export class AppComponent { utcInput = '2025-09-24T18:00:00Z'; localDate = ''; localTime = ''; localFormatted = ''; localDateOut = ''; localTimeOut = ''; utcOut = '';

onUtcInputChange() { try { const r = fromUtc(this.utcInput); this.localFormatted = r.formatted; this.localDateOut = r.date; this.localTimeOut = r.time; } catch (e: any) { this.localFormatted = e?.message ?? String(e); this.localDateOut = ''; this.localTimeOut = ''; } }

onLocalChange() { if (!this.localDate) { this.utcOut = ''; return; } try { this.utcOut = toUtc({ date: this.localDate, time: this.localTime || '00:00' }); } catch (e: any) { this.utcOut = e?.message ?? String(e); } } }

app.component.html

Make sure the pipe is imported: import { UtcToLocalPipe } from 'ngx-utc-local-time/angular'; // add to imports (standalone pipe) or declarations if you prefer a module wrapper

Why not just new Date()?

Date stores a timestamp (UTC) and formats it in your system time zone via Intl.

Converting user-local wall-clock → UTC is error-prone without care (DST boundaries).

This library wraps the common patterns into clear helpers and a simple pipe.

Temporal support: If the host provides Temporal.ZonedDateTime, toUtc() uses it for exact zone math.

Browser/Runtime Support

Modern evergreen browsers with Intl.DateTimeFormat.

Node.js ≥ 16 recommended.

If you need ancient browser support, include suitable polyfills.

Versioning

Follows semver: MAJOR.MINOR.PATCH. Breaking changes bump MAJOR. New features bump MINOR. Fixes bump PATCH.

Contributing

PRs welcome! Good first issues:

Add strict Temporal adapter (with optional polyfill).

Provide more formatting helpers (e.g., RFC-2822).

Extra Angular utilities (date/time form controls).

Conventional commits are appreciated: feat: add Temporal adapter fix: handle invalid ISO in fromUtc docs: clarify arbitrary zone caveat

Development Build: npm i npm run build

Run static demo: npx http-server demo -p 5173

open http://localhost:5173