react-universal-time-converter

A powerful React-based toolkit for converting between UTC, local, and custom timezones with beautiful UI components and reusable hooks.

Features

• 🕐 Timezone Conversion - Convert between UTC, local, and any custom timezone
• ⚡ React Hooks - Easy-to-use hooks for time manipulation
• 🎨 UI Components - Beautiful, interactive time converter component
• 📦 TypeScript - Fully typed with TypeScript
• 🌍 International - Support for all timezones via Day.js
• 🎯 Zero Config - Works with Next.js, CRA, and React Native

Installation

npm install react-universal-time-converter
# or
yarn add react-universal-time-converter
# or
pnpm add react-universal-time-converter

Quick Start

Using the TimeConverter Component

import { TimeConverter } from 'react-universal-time-converter';

function App() {
  return (
    <div>
      <TimeConverter />
    </div>
  );
}

Using Hooks

import {
  useLocalTime,
  useUTC,
  useTimezone,
  useClock,
  useCountdown,
  useRelativeTime,
  useWorldClock,
  useTimeAgo,
  useBusinessHours,
} from 'react-universal-time-converter';

function MyComponent() {
  const localTime = useLocalTime();
  const utcTime = useUTC();
  const nyTime = useTimezone(new Date(), 'America/New_York');
  const clock = useClock();
  const countdown = useCountdown('2024-12-31 23:59:59');
  const relative = useRelativeTime('2024-01-15 12:00:00');
  const timeAgo = useTimeAgo('2024-01-15 12:00:00');
  const business = useBusinessHours({
    businessHours: { start: '09:00', end: '17:00' },
  });

  return (
    <div>
      <p>Local: {localTime.formatted}</p>
      <p>UTC: {utcTime.formatted}</p>
      <p>NY: {nyTime.formatted}</p>
      <p>Clock: {clock.formatted}</p>
      <p>Countdown: {countdown.formatted}</p>
      <p>Relative: {relative.relative}</p>
      <p>Time Ago: {timeAgo.timeAgo}</p>
      <p>Business Open: {business.isOpen ? 'Yes' : 'No'}</p>
    </div>
  );
}

API Reference

Hooks

useLocalTime(date?, options?)

Returns live local time and formatted string.

const { date, formatted, update } = useLocalTime('2024-01-15 12:00:00', {
  format: 'YYYY-MM-DD HH:mm:ss',
  locale: 'en',
  updateInterval: 1000, // optional, for live updates
});

useUTC(date?, options?)

Converts any date to UTC.

const { date, formatted, update } = useUTC('2024-01-15 12:00:00', {
  format: 'YYYY-MM-DD HH:mm:ss',
});

useTimezone(date, timezone, options?)

Converts between any timezones.

const { date, formatted, update } = useTimezone(
  '2024-01-15 12:00:00',
  'America/New_York',
  {
    from: 'UTC',
    format: 'YYYY-MM-DD HH:mm:ss',
  }
);

useClock(options?)

Real-time ticking clock.

const { date, formatted, timestamp } = useClock({
  interval: 1000, // update interval in ms
  format: 'YYYY-MM-DD HH:mm:ss',
  locale: 'en',
});

useCountdown(targetDate, options?)

Countdown timer logic.

const {
  days,
  hours,
  minutes,
  seconds,
  total,
  isComplete,
  formatted,
} = useCountdown('2024-12-31 23:59:59', {
  format: 'DD:HH:mm:ss',
  onComplete: () => console.log('Time\'s up!'),
});

useRelativeTime(date, options?)

Shows relative time (e.g., "2 hours ago", "in 3 days").

const { relative, absolute, isPast, isFuture } = useRelativeTime(
  '2024-01-15 12:00:00',
  {
    updateInterval: 60000,
    locale: 'en',
    suffix: true,
  }
);

useWorldClock(options)

Display multiple timezones simultaneously (world clock).

const { clocks } = useWorldClock({
  timezones: [
    { timezone: 'America/New_York', label: 'New York' },
    { timezone: 'Europe/London', label: 'London' },
    { timezone: 'Asia/Tokyo', label: 'Tokyo' },
  ],
  updateInterval: 1000,
  format: 'YYYY-MM-DD HH:mm:ss',
});

useTimeDifference(date1, date2?, options?)

Calculate the difference between two dates.

const {
  difference,
  days,
  hours,
  minutes,
  isPast,
  isFuture,
  humanized,
} = useTimeDifference('2024-12-31', '2024-01-01', {
  unit: 'days',
  absolute: false,
});

useBusinessHours(options)

Check if current time is within business hours for a timezone.

const {
  isOpen,
  isClosed,
  nextOpenTime,
  timeUntilOpen,
  currentTime,
} = useBusinessHours({
  timezone: 'America/New_York',
  businessHours: {
    start: '09:00',
    end: '17:00',
    daysOfWeek: [1, 2, 3, 4, 5], // Monday to Friday
  },
});

useTimeAgo(date, options?)

Show human-readable "time ago" format (e.g., "2 hours ago", "3 days ago").

const {
  timeAgo,
  fullDate,
  isRecent,
  isToday,
  isYesterday,
} = useTimeAgo('2024-01-15 12:00:00', {
  updateInterval: 30000,
  showSeconds: true,
});

useTimezoneOffset(timezone?, date?)

Get timezone offset information.

const {
  offset,
  offsetMinutes,
  offsetHours,
  abbreviation,
  isDST,
} = useTimezoneOffset('America/New_York');

useIsSameDay(date1, date2?, timezone?)

Check if two dates are the same day (in a specific timezone).

const {
  isSameDay,
  isSameMonth,
  isSameYear,
  isSameWeek,
  dayDifference,
} = useIsSameDay('2024-01-15', '2024-01-15', 'America/New_York');

useTimeRange(range, options?)

Work with time ranges.

const {
  start,
  end,
  startFormatted,
  endFormatted,
  duration,
  isWithinRange,
  isPast,
  isFuture,
  isActive,
} = useTimeRange(
  {
    start: '2024-01-01 00:00:00',
    end: '2024-01-31 23:59:59',
  },
  {
    timezone: 'America/New_York',
    format: 'YYYY-MM-DD HH:mm:ss',
  }
);

Components

<LocalTime />

Display local time.

<LocalTime
  date="2024-01-15 12:00:00"
  format="YYYY-MM-DD HH:mm:ss"
  className="my-time"
/>

// With render prop
<LocalTime date="2024-01-15 12:00:00">
  {(formatted, date) => <div>{formatted}</div>}
</LocalTime>

<Countdown />

Countdown timer component.

<Countdown
  targetDate="2024-12-31 23:59:59"
  format="DD:HH:mm:ss"
  onComplete={() => alert('Time\'s up!')}
/>

// With render prop
<Countdown targetDate="2024-12-31 23:59:59">
  {(countdown) => (
    <div>
      {countdown.days} days, {countdown.hours} hours
    </div>
  )}
</Countdown>

<TimeConverter />

Interactive time converter with UTC, Local, and Custom timezone conversion.

<TimeConverter
  initialDate="2024-01-15 12:00:00"
  initialTimezone="America/New_York"
  darkMode={false}
  showCopyButton={true}
  dateFormat="YYYY-MM-DD HH:mm:ss"
/>

Props:

• initialDate?: string | Date | number - Initial date to convert
• initialTimezone?: string - Initial timezone selection
• className?: string - Additional CSS classes
• darkMode?: boolean - Enable dark mode (default: false)
• showCopyButton?: boolean - Show copy to clipboard buttons (default: true)
• dateFormat?: string - Date format string (default: 'YYYY-MM-DD HH:mm:ss')

Utilities

toLocal(date, options?)

Convert a date to local timezone.

import { toLocal } from 'react-universal-time-converter';

const { date, formatted } = toLocal('2024-01-15 12:00:00', {
  format: 'YYYY-MM-DD HH:mm:ss',
});

toUTC(date, options?)

Convert a date to UTC.

import { toUTC } from 'react-universal-time-converter';

const { date, formatted } = toUTC('2024-01-15 12:00:00');

toTimezone(date, options)

Convert a date between timezones.

import { toTimezone } from 'react-universal-time-converter';

const { date, formatted } = toTimezone('2024-01-15 12:00:00', {
  from: 'UTC',
  to: 'America/New_York',
  format: 'YYYY-MM-DD HH:mm:ss',
});

detectTimezone()

Detect the user's current timezone.

import { detectTimezone } from 'react-universal-time-converter';

const tz = detectTimezone(); // e.g., "America/New_York"

formatDate(date, options?)

Format a date with custom format and locale.

import { formatDate } from 'react-universal-time-converter';

const formatted = formatDate('2024-01-15 12:00:00', {
  format: 'YYYY-MM-DD',
  locale: 'en',
});

getAvailableTimezones()

Get all available timezones.

import { getAvailableTimezones } from 'react-universal-time-converter';

const timezones = getAvailableTimezones();

Use Cases

This library is perfect for:

• 🌍 International Applications - Multi-timezone support for global users
• ⏰ Real-Time Clocks - Live time displays and dashboards
• 🎯 Countdown Timers - Product launches, sales, events, deadlines
• 📅 Calendar & Scheduling - Meeting schedulers, booking systems
• 🔔 Notifications - Activity feeds, timestamps, chat applications
• 📊 Analytics - Time-based data visualization and reporting
• 🛠️ Developer Tools - Admin panels, system monitoring
• 🎮 Gaming - Game events, tournaments, limited-time offers
• 📱 Mobile Apps - Travel apps, weather apps, fitness tracking
• 🏢 Enterprise - CRM systems, support ticketing, HR platforms
• 🎓 Education - Course scheduling, exam timers, assignment deadlines
• 🔐 Security - Audit logs, compliance reporting

📖 See detailed use cases →

Examples

Basic Time Display

import { LocalTime } from 'react-universal-time-converter';

function App() {
  return (
    <div>
      <h1>Current Local Time</h1>
      <LocalTime format="YYYY-MM-DD HH:mm:ss" />
    </div>
  );
}

Timezone Conversion

import { useTimezone } from 'react-universal-time-converter';

function TimezoneDisplay() {
  const nyTime = useTimezone(new Date(), 'America/New_York');
  const tokyoTime = useTimezone(new Date(), 'Asia/Tokyo');

  return (
    <div>
      <p>New York: {nyTime.formatted}</p>
      <p>Tokyo: {tokyoTime.formatted}</p>
    </div>
  );
}

Countdown Timer

import { Countdown } from 'react-universal-time-converter';

function EventCountdown() {
  return (
    <div>
      <h2>New Year Countdown</h2>
      <Countdown
        targetDate="2024-12-31 23:59:59"
        format="DD:HH:mm:ss"
        onComplete={() => alert('Happy New Year!')}
      />
    </div>
  );
}

Full Time Converter UI

import { TimeConverter } from 'react-universal-time-converter';

function App() {
  return (
    <div className="container">
      <TimeConverter
        initialDate={new Date()}
        darkMode={true}
        showCopyButton={true}
      />
    </div>
  );
}

Styling

The TimeConverter component uses Tailwind CSS classes. If you're not using Tailwind in your project, you can:

1. Install Tailwind CSS in your project
2. Use the component with custom className props
3. Override styles with CSS

The component is designed to work with or without Tailwind CSS.

TypeScript

This library is fully typed with TypeScript. All exports include type definitions.

import type {
  UseLocalTimeReturn,
  UseUTCReturn,
  UseTimezoneReturn,
  LocalTimeProps,
  CountdownProps,
  TimeConverterProps,
} from 'react-universal-time-converter';

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Changelog

1.0.0

• Initial release
• Hooks: useLocalTime, useUTC, useTimezone, useClock, useCountdown
• Components: LocalTime, Countdown, TimeConverter
• Utilities: toLocal, toUTC, toTimezone, detectTimezone, formatDate