@itomo/locale-react

React hooks and UI helpers built on top of @itomo/locale-core.

• Context-based locale state (country, currency, timezone)
• Ready-to-use picker components
• Hook wrappers for all major core queries

Install

pnpm add @itomo/locale-core @itomo/locale-react react

Quick start

import { LocaleProvider, CountryPicker, useCountry } from "@itomo/locale-react";

function CurrentCountry() {
  const country = useCountry();
  return <p>{country?.name.common ?? "No country selected"}</p>;
}

export function App() {
  return (
    <LocaleProvider defaultCountry="VN">
      <CountryPicker />
      <CurrentCountry />
    </LocaleProvider>
  );
}

Public API

Context and provider

• LocaleProvider(props)
• useLocale()
• useCountry(), useCurrency(), useTimezone()

Country hooks

• Lookups: useCountryByCca2(cca2), useCountryByCca3(cca3), useCountryByCioc(cioc), useCountryByNumeric(numeric), useCountryByAnyCode(code)
• Lists and filters: useAllCountries(), useIndependentCountries(), useUNMemberCountries(), useCountriesByRegion(region), useCountriesByContinent(continent), useCountriesByLanguage(iso6393), useCountriesByCurrency(alpha3), useCountriesByTimezone(tzId), useCountriesByCallingCode(code), useCountriesByRegionalBloc(bloc), useBorderingCountries(cca3)
• Names/search: useSearchCountries(query, locale?), useCountryName(cca2, locale?), useCountryOfficialName(cca2, locale?), useCountryNativeName(cca2, iso6393?)
• Subdivisions: useSubdivisions(cca2), useSubdivisionByCode(cca2, code), useSubdivisionsByType(cca2, type)
• Localized helpers: useAllCountriesLocalized(locale), useSearchCountriesLocalized(query, locale)

Currency hooks

• Lookups: useCurrencyByAlpha3(alpha3), useCurrencyByNumeric(numeric), useCurrencyByAnyCode(code), useCurrencyByCode(alpha3)
• Lists and filters: useAllCurrencies(), useActiveCurrencies(), useDeprecatedCurrencies(), useCurrenciesByType(type), useCurrenciesByCountry(cca2)
• Names/search/format: useSearchCurrencies(query), useCurrencyName(alpha3, locale?), useCurrencySymbol(alpha3, locale?), useFormatAmount(amount, alpha3, locale?), useFormattedAmount(amount, alpha3, locale?)
• Localized helpers: useAllCurrenciesLocalized(locale), useSearchCurrenciesLocalized(query, locale)

Language hooks

• Lookups: useLanguageByIso6391(code), useLanguageByIso6392b(code), useLanguageByIso6392t(code), useLanguageByIso6393(code), useLanguageByAnyCode(code), useLanguageByCode(iso6393)
• Lists and filters: useAllLanguages(), useLivingLanguages(), useRtlLanguages(), useLanguagesByFamily(family), useLanguagesByCountry(cca2), useLanguagesByScript(iso15924)
• Names/search: useSearchLanguages(query, locale?), useLanguageName(iso6393, locale?)
• Localized helpers: useAllLanguagesLocalized(locale), useSearchLanguagesLocalized(query, locale)

Script hooks

• useAllScripts()
• useScriptByCode(code)

Timezone hooks

• Lookups and filters: useAllTimezones(), useTimezoneById(tzId), useTimezonesByCountry(cca2), useTimezonesByUtcOffset(offset), useTimezonesByRegion(region), useCanonicalTimezones()
• Search and utilities: useSearchTimezones(query), useCurrentUtcOffset(tzId), useDaylightSavingActive(tzId), useReinterpretInTimezone(date, fromTz, toTz)
• Localized helpers: useTimezoneName(tzId, locale), useAllTimezonesLocalized(locale), useSearchTimezonesLocalized(query, locale)

i18n and locale utility hooks

• useLoadTranslation(locale), useSupportedTranslationLocales(), useSupportedLanguages(), useLocaleSupported(locale)
• useBuildLocaleTag(language, script?, region?), useParseLocaleTag(tag)
• useCountryFromLocale(locale), useLanguageFromLocale(locale)
• usePhoneCode(cca2), useParsePhonePrefix(phone)
• useTextDirection(iso6391OrLocale), useIsRtlLanguage(iso6391OrLocale)

Components

• CountryPicker(props)
• CurrencyPicker(props)
• TimezonePicker(props)
• CountrySelect(props) (headless/custom-render capable)

Notes

• All hooks are pure wrappers around @itomo/locale-core and use memoization to avoid recomputation unless inputs change.
• Requires React 18+.

License

MIT © iTomo Vietnam