@payello-ui/react-country

A lightweight country detection context for React and React Native applications, with no external dependencies. This package allows you to easily handle and manipulate country data within your application through a React context. It includes functionalities for setting and retrieving the current country, detecting the country automatically based on various signals, and providing a list of permitted countries.

Installation

npm install @payello-ui/react-country
# or
yarn add @payello-ui/react-country

Usage

Setting Up

First, wrap your main component or the specific part of your app that requires country context with CountryProvider:

import React from 'react';
import { CountryProvider } from '@payello-ui/react-country';

function App() {
  return (
    <CountryProvider>
      {/* Rest of your app components */}
    </CountryProvider>
  );
}

export default App;

Accessing and Setting the Country

Inside any component wrapped by CountryProvider, you can access and set the current country using the useCountry hook:

import React from 'react';
import { useCountry } from '@payello-ui/react-country';

function MyComponent() {
  const [country, setCountry] = useCountry();

  return (
    <div>
      <p>Current country: {country}</p>
      <button onClick={() => setCountry('US')}>Set to US</button>
    </div>
  );
}

export default MyComponent;

Country Detection

This package provides a utility to attempt automatic detection of the user's country based on the request information. This can include query parameters, cookies, hostname's top-level domain, CloudFlare headers, and accepted languages header from the browser.

import { requestCountry } from '@payello-ui/react-country';

async function detectCountry(request) {
  const country = await requestCountry(request, {
    // Optional configuration
  });
  console.log(country); // Outputs the detected country code or null
}

// Example usage with a fetch event in a service worker or Cloudflare Worker
self.addEventListener('fetch', (event) => {
  event.respondWith(detectCountry(event.request));
});

The requestCountry function supports a variety of options for detecting the country, allowing you to customize the detection process to fit your needs.

API

Below are the main exports of @payello-ui/react-country:

• CountryProvider: A React context provider for wrapping your application or parts of it.
• useCountry: A React hook for accessing and setting the current country within components wrapped by CountryProvider.
• requestCountry: A function for detecting the country based on a request, useful for server-side rendering or API endpoints.
• CountryManager: Contains the list of all permitted countries and initial default country.
• extractCookieValue: Utility function for extracting a value from a cookie string.
• getBrowserLanguages: Utility function for parsing the browser's Accept-Language header.

Contributing

We welcome contributions to make this package better. If you find a bug or would like a new feature, feel free to open an issue or create a pull request.

License

This package is licensed under the MIT License. See LICENSE file for details.