Skip to content

README.md

Latest commit

 

History

History
103 lines (76 loc) · 2.82 KB

README.md

File metadata and controls

103 lines (76 loc) · 2.82 KB
Raw

React Native Timezone

Fast, privacy-first timezone and country detection for React Native with zero extra permissions.

react-native-timezone gives you:

  • Current timezone ID
  • Best current country from telephony (network-first, then SIM fallback)
  • Locale country fallback
  • Android auto-timezone setting status

Why this package

Privacy-first

No location permission and no READ_PHONE_STATE needed.

Native + fast

TurboModule implementation with synchronous reads for simple integration.

Expo development builds ready

Works with Expo prebuild/dev-client workflows.

Lightweight

Measured from the v3.2.1 package (February 7, 2026):

  • Publish tarball: ~13.2 KB (varies slightly between pack runs)
  • Installed package contents (unpacked): 52,165 bytes (~51.0 KB)
  • JS runtime payload (CommonJS entry used by Metro): 1,288 bytes raw, 706 bytes gzip

Compatibility

React Native New Architecture Status
>= 0.71.0 Supported Compatible
0.76.x Default New Arch Verified in this repo
0.81.x Default New Arch Verified in example app

iOS note on telephony APIs

Apple has deprecated CTCarrier APIs with no direct replacement. This can make telephony country unavailable on newer iOS versions, depending on device/network/privacy behavior.

Recommended pattern:

const bestCountry =
  Timezone.getRegionByTelephony() ?? Timezone.getRegionByLocale();

Installation

yarn add react-native-timezone

For iOS:

npx pod-install

Expo (development builds)

npx expo install react-native-timezone
npx expo prebuild
npx expo run:ios

Usage

import { useEffect } from 'react';
import Timezone from 'react-native-timezone';

export default function App() {
  useEffect(() => {
    const timezone = Timezone.getTimeZone();
    const isAutoTimeZoneEnabled = Timezone.isAutoTimeZoneEnabled();
    const telephonyRegion = Timezone.getRegionByTelephony();
    const localeRegion = Timezone.getRegionByLocale();
    const bestCountry = telephonyRegion ?? localeRegion;

    console.log({
      timezone,
      isAutoTimeZoneEnabled,
      telephonyRegion,
      localeRegion,
      bestCountry,
    });
  }, []);

  return null;
}

See the example app.

API

API Description
getTimeZone() Returns current timezone ID (for example Asia/Colombo, Europe/Berlin).
isAutoTimeZoneEnabled() Android only. Returns true or false; returns null on iOS.
getRegionByTelephony() Returns best current telephony country (network-first, then SIM fallback) as uppercase ISO code (for example LK, US) or null.
getRegionByLocale() Returns locale country as uppercase ISO code (for example LK, US) or null.