{"id":23103930,"url":"https://github.com/benaubin/react-headless-phone-input","last_synced_at":"2025-08-16T15:32:52.846Z","repository":{"id":39069289,"uuid":"275912402","full_name":"benaubin/react-headless-phone-input","owner":"benaubin","description":"Headless phone number input component for React. Because phone numbers are hard.","archived":false,"fork":false,"pushed_at":"2023-07-31T16:40:53.000Z","size":1286,"stargazers_count":41,"open_issues_count":20,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-12T23:34:12.052Z","etag":null,"topics":["e164","input","phone-formatting","phone-input","phone-number","phone-number-input","phone-number-validation","react","telephone-number-parser"],"latest_commit_sha":null,"homepage":"https://codesandbox.io/s/react-headless-phone-input-demo-ygow2?file=/src/App.js","language":"TypeScript","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/benaubin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2020-06-29T19:52:46.000Z","updated_at":"2024-11-21T09:53:06.000Z","dependencies_parsed_at":"2024-06-19T04:01:40.277Z","dependency_job_id":"f7e38683-99b3-4864-80ca-bd36269f5147","html_url":"https://github.com/benaubin/react-headless-phone-input","commit_stats":{"total_commits":40,"total_committers":2,"mean_commits":20.0,"dds":"0.050000000000000044","last_synced_commit":"91d742c01c979738eb2a6d7d934143f436cc9b55"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benaubin%2Freact-headless-phone-input","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benaubin%2Freact-headless-phone-input/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benaubin%2Freact-headless-phone-input/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benaubin%2Freact-headless-phone-input/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benaubin","download_url":"https://codeload.github.com/benaubin/react-headless-phone-input/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230044010,"owners_count":18164103,"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":["e164","input","phone-formatting","phone-input","phone-number","phone-number-input","phone-number-validation","react","telephone-number-parser"],"created_at":"2024-12-17T00:29:53.393Z","updated_at":"2024-12-17T00:29:53.491Z","avatar_url":"https://github.com/benaubin.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React Headless Phone Input\n\nA headless phone number input component built for usability.\n\n[Phone numbers are hard][falsehoods]. Users expect to be able to enter phone numbers in the format they're used to. Here's the problem: most people are used to national - or even local phone number formats. If you offload phone number validation to your backend (or an API), resolving the ambiguity becomes difficult or even impossible.\n\nThis component helps you build a UI that gracefully guides your users towards unambiguous phone number formats. And you get the result in standard e164 format: ready for use with any telephony service.\n\nOther libraries are generally heavy (phone number rulesets can be big - 99.1% of this library's [footprint][bundlephobia] is due to [libphonenumber-js]), force you to use their UI, and can't handle copy \u0026 paste or edit-in-place. `react-headless-phone-input` is designed for usability-first, and lets you bring your own input components. In fact, your existing input fields will almost certainly work with no modifications. Plus, it supports optional lazy-loading with progressive enhancement powered by React Suspense.\n\nBuilt with React Hooks.\n\n[Demo][demo]\n\n## Install\n\nInstall both react-headless-input and [libphonenumber-js]:\n\n```sh\nnpm i --save react-headless-phone-input libphonenumber-js\n```\n\nor\n\n```sh\nyarn add react-headless-phone-input libphonenumber-js\n```\n\n## Features\n\n- 100% headless: Bring your own UI. You can use almost any input component you already have\n- Lets users copy \u0026 paste phone numbers of any format\n- Typescript support\n- Built-in lazy-loading with progressive enhancement (clocks in at 40KB without lazy-loading)\n- Detects the associated country, enabling international phone input.\n- Lets users copy \u0026 paste phone numbers of any format\n- Acts like a normal input: Doesn’t glitch if a user edits in-place or deletes template characters\n- Validates number plausibility\n- External state is standard e164 format\n\n## Example\n\nThis library is headless: you bring your own UI, but it's almost as easy as using regular inputs.\n\nHere's an example using [tiny-flag-react] to show the flag associated with the number's country:\n\n```js\nimport TinyFlagReact from \"tiny-flag-react\";\nimport PhoneFormatter from \"react-headless-phone-input\";\n// import PhoneFormatter from \"react-headless-phone-input/lazy\"; RECOMMENDED\n\nconst [e164, setE164] = useState(\"\");\n\n\u003cPhoneFormatter defaultCountry=\"US\" value={e164} onChange={setE164}\u003e\n  {({ country, impossible, onBlur, onInputChange, inputValue }) =\u003e {\n    return (\n      \u003c\u003e\n        \u003cdiv style={{ display: \"flex\", alignItems: \"center\" }}\u003e\n          \u003cspan\n            style={{\n              fontSize: \"24px\",\n            }}\u003e\n            {country ? (\n              \u003cTinyFlagReact\n                country={country}\n                alt={country + \" flag\"}\n                fallbackImageURL={`https://cdn.jsdelivr.net/npm/react-flagkit@1.0.2/img/SVG/${country}.svg`}\n              /\u003e\n            ) : (\n              \u003c\u003e✆\u003c/\u003e\n            )}\n          \u003c/span\u003e\n          \u003cinput\n            type=\"tel\"\n            value={inputValue}\n            onBlur={onBlur}\n            onChange={(e) =\u003e onInputChange(e.target.value)}\n          /\u003e\n        \u003c/div\u003e\n        {impossible \u0026\u0026 (\n          \u003cdiv style={{ color: \"red\" }}\u003eImpossible phone number\u003c/div\u003e\n        )}\n      \u003c/\u003e\n    );\n  }}\n\u003c/PhoneFormatter\u003e;\n```\n\n[Demo][demo]\n\n## Performance\n\nDue to this library's dependence on [libphonenumber-js], it clocks in at [38.7KB minified + gzipped][bundlephobia].\nTo improve your user's experience, react-headless-phone-component supports lazy loading with React Suspense with\nprogressive auto-enachement. If your bundler supports dynamic imports and are using a compatible version of React,\njust swap `react-headless-phone-input` for `react-headless-phone-input/lazy`.\n\nYour UI will render and can be used immediately. Once `react-headless-phone-input` loads, the component will be\nautomatically upgraded. No other changes are required.\n\n```js\nimport PhoneFormatter from \"react-headless-phone-input/lazy\";\n```\n\n## License\n\n[MIT](LICENSE)\n\n[falsehoods]: https://github.com/google/libphonenumber/blob/master/FALSEHOODS.md\n[libphonenumber-js]: https://www.npmjs.com/package/libphonenumber-js\n[tiny-flag-react]: https://github.com/benaubin/tiny-flag-react\n[bundlephobia]: https://bundlephobia.com/result?p=react-headless-phone-input\n[demo]: https://codesandbox.io/s/react-headless-phone-input-demo-ygow2?file=/src/App.js\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenaubin%2Freact-headless-phone-input","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenaubin%2Freact-headless-phone-input","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenaubin%2Freact-headless-phone-input/lists"}