{"id":28100274,"url":"https://github.com/theo-sim-dev/use-country","last_synced_at":"2026-02-22T12:02:59.202Z","repository":{"id":287493191,"uuid":"964918983","full_name":"theo-sim-dev/use-country","owner":"theo-sim-dev","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-12T03:09:02.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T04:23:16.042Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theo-sim-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-12T03:06:46.000Z","updated_at":"2025-04-12T03:08:48.000Z","dependencies_parsed_at":"2025-04-12T04:23:21.517Z","dependency_job_id":null,"html_url":"https://github.com/theo-sim-dev/use-country","commit_stats":null,"previous_names":["theo-sim-dev/use-country"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theo-sim-dev%2Fuse-country","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theo-sim-dev%2Fuse-country/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theo-sim-dev%2Fuse-country/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theo-sim-dev%2Fuse-country/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theo-sim-dev","download_url":"https://codeload.github.com/theo-sim-dev/use-country/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254003407,"owners_count":21997882,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-13T18:32:23.229Z","updated_at":"2026-02-22T12:02:59.096Z","avatar_url":"https://github.com/theo-sim-dev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# useCountry\n\n[![npm](https://img.shields.io/npm/v/use-country?color=orange)](https://www.npmjs.com/package/use-country)\n[![license](https://img.shields.io/badge/license-MIT-green)](https://www.npmjs.com/package/use-country)\n[![typescript](https://img.shields.io/badge/typescript-blue?logo=typescript\u0026logoColor=f5f5f5)](https://www.npmjs.com/package/use-country)\n[![react](https://img.shields.io/badge/react-blue?logo=react)](https://www.npmjs.com/package/use-country)\n\n📍**Detect your visitor's country!**\n\n`useCountry` is a lightweight React hook that determines a country using the IP address via [Country.is](https://country.is/) API.\n\nCountry.is is completely free for both personal and commercial use, and so is `useCountry`.\n\n## Demo\n\n[![Edit mui-alert-provider demo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/use-country-demo-52pvzy)\n\n## Features\n\n[Country.is](https://country.is/) is a free IP-to-country geolocation API that returns a visitor's country based on their IP address. It has been reliably operating for over a decade. For more information about usage limits and capabilities, please visit the website.\n\nThis package relies on `country-list-with-dial-code-and-flag`, which is another cool library containing lots of useful methods to deal with countries. Please visit their [npm](https://www.npmjs.com/package/country-list-with-dial-code-and-flag) for more information.\n\n## Installation\n\n```bash\nnpm install use-country country-list-with-dial-code-and-flag\n```\n\nor\n\n```bash\nyarn add use-country country-list-with-dial-code-and-flag\n```\n\n## Usage\n\n[Check out this playground](https://codesandbox.io/p/sandbox/use-country-demo-52pvzy) 🎮\n\nSimply import `useCountry` into your React component. The hook provides the detected country, loading state, error (if any), and a method to manually fetch the country again.\n\n```tsx\nimport React from \"react\";\nimport { useCountry } from \"use-country\";\n\nconst App = () =\u003e {\n  const { country, loading, error, getCountryByIP } = useCountry({ fallback: \"US\" });\n\n  if (loading) return \u003cp\u003eLoading...\u003c/p\u003e;\n  if (error) return \u003cp\u003eError: {error.message}\u003c/p\u003e;\n\n  return (\n    \u003cdiv\u003e\n      \u003ch1\u003eDetected Country\u003c/h1\u003e\n      {country ? (\n        \u003cdiv\u003e\n          \u003cp\u003eCountry Name: {country.name}\u003c/p\u003e\n          \u003cp\u003eCountry Code: {country.code}\u003c/p\u003e\n          \u003cp\u003eDial Code: {country.dial_code}\u003c/p\u003e\n          \u003cimg src={country.flag} alt={`${country.name} flag`} width=\"50\" /\u003e\n        \u003c/div\u003e\n      ) : (\n        \u003cp\u003eNo country detected.\u003c/p\u003e\n      )}\n      \u003cbutton onClick={getCountryByIP}\u003eRetry\u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport default App;\n```\n\n## API\n\n### `useCountry` hook\n\n#### Receives `UseCountryProps`\n\n| Properties | Type                  | Description                                                                 |\n|------------|-----------------------|-----------------------------------------------------------------------------|\n| `fallback` | `string \\| undefined` | An optional ISO country code to use as a fallback if the API call fails. e.g., \"FR\" |\n\n#### Returns `UseCountryResult`\n\n| Properties         | Type                          | Description                                                                 |\n|--------------------|-------------------------------|-----------------------------------------------------------------------------|\n| `country`          | `Country \\| undefined`        | A detected `Country` object. `undefined` if no country is detected.     \t|\n| `error`            | `Error \\| undefined`          | An error object if an error occurs during the fetch process. `undefined` if there is no error.|\n| `loading`          | `boolean`                     | A boolean indicating whether the country detection is in progress.          |\n| `getCountryByIP`   | `() =\u003e Promise\u003cvoid\u003e`         | A method to manually retry fetching the country.                            |\n\n### Important types and interfaces\n\n#### `Country`\n\nExposed directly from `country-list-with-dial-code-and-flag`. Please refer to their official [documentation](https://zin-kyaw-kyaw.gitbook.io/country-flags/usage#country) for more details.\n\n| Property         | Type     | Description                                                   |\n|------------------|----------|---------------------------------------------------------------|\n| `name`           | `string` | The name of the country (e.g., \"Canada\").                     |\n| `flag`           | `string` | The emoji representation of the country's flag (e.g., \"🇨🇦\"). |\n| `code`           | `string` | The ISO country code (e.g., \"CA\").                            |\n| `dialCode`       | `string` | The country's dial code (e.g., \"+1\").                         |\n| `currency`       | `string` | The name of the country's currency (e.g., \"Canadian Dollar\"). |\n| `currencySymbol` | `string` | The symbol of the country's currency (e.g., \"$\").             |\n| `currencyCode`   | `string` | The ISO currency code (e.g., \"CAD\").                          |\n| `localName`      | `string` | The local name of the country in its native language.         |\n\n##### Example\n\n```json\n{\n  \"name\": \"Canada\",\n  \"flag\": \"🇨🇦\",\n  \"code\": \"CA\",\n  \"dialCode\": \"+1\",\n  \"currency\": \"Canadian Dollar\",\n  \"currencySymbol\": \"$\",\n  \"currencyCode\": \"CAD\",\n  \"localName\": \"Canada\"\n}\n```\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheo-sim-dev%2Fuse-country","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheo-sim-dev%2Fuse-country","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheo-sim-dev%2Fuse-country/lists"}