Timezone-friendly NPM

TimeZoneFriendly

TimeZoneFriendly is a lightweight, easy-to-use library for automatically converting and formatting date and time strings based on the user's time zone. It’s designed for both JavaScript and React, with features like customizable friendly text (e.g., "2 hours ago"), time zone conversions, and flexible date formats.

Features

Time Zone Conversion: Easily convert a date or time from one time zone to another.
Customizable Date and Time Formats: Display dates in any format you need.
Friendly Time Display: Display relative times like "yesterday" or "in 3 days".
Customizable Friendly Text: Replace "0 minutes ago" with "just now", or future dates with "soon".
Multiple Input Formats: Supports ISO strings, Unix timestamps, and custom date formats.
Future Date Handling: Displays phrases for future dates like "in 2 hours" or "next week".
Optional Date and Time Display: Show just the date, just the time, or both based on your needs.
Caching: Optimizes performance by caching results for repeated date inputs.
TypeScript Support: Fully typed for TypeScript users.

Installation

You can install the package via npm:

npm install timezone-friendly

Usage

Here’s a basic example of how to use TimeZoneFriendly in a React component:

import React from "react";
import TimeZoneFriendly from "timezone-friendly";

const App = () => {
  const date = "2024-09-26T12:00:00Z"; // Example ISO date

  // Example of converting a date to a user's local time zone and formatting it.
  const formattedDate = TimeZoneFriendly(date, { friendly: true });

  return (
    <div>
      <h1>TimeZoneFriendly Demo</h1>
      <p>Friendly Date: {formattedDate}</p>
    </div>
  );
};

export default App;

Props (Options)

Prop	Type	Description
`friendly`	`boolean`	Shows relative time like "2 hours ago" when `true`. Defaults to `false`.
`formatString`	`string`	Custom date format string. Defaults to `"yyyy-MM-dd HH:mm:ss"`.
`locale`	`string`	Locale code for formatting (e.g., "en", "fr", "es"). Defaults to `"en"`.
`targetTimeZone`	`string`	Converts date to a specific time zone (e.g., `"America/New_York"`).
`inputFormat`	`string`	Format for parsing custom date inputs (e.g., `"dd/MM/yyyy"`).
`customText`	`object`	Object to override default text for "just now" and "soon".
`showDate`	`boolean`	Controls whether the date is shown. Defaults to `true`.
`showTime`	`boolean`	Controls whether the time is shown. Defaults to `true`.

Examples

Friendly Time Display Show relative times like "2 hours ago" or "yesterday":

const friendlyTime = TimeZoneFriendly("2024-09-26T12:00:00Z", { friendly: true });

Custom Date Format Display a date in a custom format:

const customFormattedDate = TimeZoneFriendly("2024-09-26T12:00:00Z", { 
  friendly: false, 
  formatString: "dd/MM/yyyy" 
});

Time Zone Conversion Convert a date to a specific time zone:

const timeZoneConvertedDate = TimeZoneFriendly("2024-09-26T12:00:00Z", { 
  friendly: false, 
  targetTimeZone: "America/New_York" 
});

Custom Friendly Text Customize the display of "just now" and "soon":

const customText = TimeZoneFriendly(new Date(), { 
  friendly: true, 
  customText: { justNow: "just now", soon: "soon" }
});

Optional Date and Time Display Show only the date or only the time:

const dateOnly = TimeZoneFriendly("2024-09-26T12:00:00Z", { friendly: false, showDate: true, showTime: false });
const timeOnly = TimeZoneFriendly("2024-09-26T12:00:00Z", { friendly: false, showDate: false, showTime: true });

Accessibility

The TimeZoneFriendly package is designed to be used in accessible applications, with keyboard and screen reader support in mind when rendering dates and times in a user-friendly format.