{"id":2007,"url":"https://github.com/marmelroy/PhoneNumberKit","last_synced_at":"2025-08-06T16:32:21.591Z","repository":{"id":37502376,"uuid":"43208710","full_name":"marmelroy/PhoneNumberKit","owner":"marmelroy","description":"A Swift framework for parsing, formatting and validating international phone numbers. Inspired by Google's libphonenumber.","archived":false,"fork":false,"pushed_at":"2025-07-22T00:38:03.000Z","size":3158,"stargazers_count":5273,"open_issues_count":14,"forks_count":835,"subscribers_count":66,"default_branch":"master","last_synced_at":"2025-08-01T00:43:25.835Z","etag":null,"topics":["contacts","formatting","google-libphonenumber","parsing","phone-number","swift","validation"],"latest_commit_sha":null,"homepage":"","language":"Swift","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/marmelroy.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":"2015-09-26T14:37:36.000Z","updated_at":"2025-07-30T10:51:27.000Z","dependencies_parsed_at":"2023-10-04T15:26:04.670Z","dependency_job_id":"c70bc307-1ea0-4955-9f3c-c2f76dd4a6c9","html_url":"https://github.com/marmelroy/PhoneNumberKit","commit_stats":{"total_commits":762,"total_committers":121,"mean_commits":6.297520661157025,"dds":"0.47112860892388453","last_synced_commit":"24c2f394c1f0591bf7e3e48c23f64ca52e3f1933"},"previous_names":[],"tags_count":102,"template":false,"template_full_name":null,"purl":"pkg:github/marmelroy/PhoneNumberKit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmelroy%2FPhoneNumberKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmelroy%2FPhoneNumberKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmelroy%2FPhoneNumberKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmelroy%2FPhoneNumberKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marmelroy","download_url":"https://codeload.github.com/marmelroy/PhoneNumberKit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmelroy%2FPhoneNumberKit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268317783,"owners_count":24231420,"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","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["contacts","formatting","google-libphonenumber","parsing","phone-number","swift","validation"],"created_at":"2024-01-05T20:16:01.074Z","updated_at":"2025-08-06T16:32:21.582Z","avatar_url":"https://github.com/marmelroy.png","language":"Swift","readme":"![PhoneNumberKit](https://cloud.githubusercontent.com/assets/889949/20864386/a1307950-b9ef-11e6-8a58-e9c5103738e7.png)\n[![Platform](https://img.shields.io/cocoapods/p/PhoneNumberKit.svg?maxAge=2592000\u0026style=for-the-badge)](http://cocoapods.org/?q=PhoneNumberKit)\n![GitHub Workflow Status (with branch)](https://img.shields.io/github/actions/workflow/status/marmelroy/PhoneNumberKit/pr.yml?branch=master\u0026label=tests\u0026style=for-the-badge) [![Version](http://img.shields.io/cocoapods/v/PhoneNumberKit.svg?style=for-the-badge)](http://cocoapods.org/?q=PhoneNumberKit)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=for-the-badge)](https://github.com/Carthage/Carthage)\n\n# PhoneNumberKit\n\nSwift 5.3 framework for parsing, formatting and validating international phone numbers.\nInspired by Google's libphonenumber.\n\n## Features\n\n|                  | Features                                                                                    |\n| ---------------- | ------------------------------------------------------------------------------------------- |\n| :phone:          | Validate, normalize and extract the elements of any phone number string.                    |\n| :100:            | Simple Swift syntax and a lightweight readable codebase.                                    |\n| :checkered_flag: | Fast. 1000 parses -\u003e ~0.4 seconds.                                                          |\n| :books:          | Best-in-class metadata from Google's libPhoneNumber project.                                |\n| :trophy:         | Fully tested to match the accuracy of Google's JavaScript implementation of libPhoneNumber. |\n| :iphone:         | Built for iOS. Automatically grabs the default region code from the phone.                  |\n| 📝               | Editable (!) AsYouType formatter for UITextField.                                           |\n| :us:             | Convert country codes to country names and vice versa                                       |\n\n## Usage\n\nImport PhoneNumberKit at the top of the Swift file that will interact with a phone number.\n\n```swift\nimport PhoneNumberKit\n```\n\nAll of your interactions with PhoneNumberKit happen through a PhoneNumberUtility object. The first step you should take is to allocate one.\n\nA PhoneNumberUtility instance is relatively expensive to allocate (it parses the metadata and keeps it in memory for the object's lifecycle), you should try and make sure PhoneNumberUtility is allocated once and deallocated when no longer needed.\n\n```swift\nlet phoneNumberUtility = PhoneNumberUtility()\n```\n\nTo parse a string, use the parse function. The region code is automatically computed but can be overridden if needed. PhoneNumberKit automatically does a hard type validation to ensure that the object created is valid, this can be quite costly performance-wise and can be turned off if needed.\n\n```swift\ndo {\n    let phoneNumber = try phoneNumberUtility.parse(\"+33 6 89 017383\")\n    let phoneNumberCustomDefaultRegion = try phoneNumberUtility.parse(\"+44 20 7031 3000\", withRegion: \"GB\", ignoreType: true)\n}\ncatch {\n    print(\"Generic parser error\")\n}\n```\n\nIf you need to parse and validate a large amount of numbers at once, PhoneNumberKit has a special, lightning fast array parsing function. The default region code is automatically computed but can be overridden if needed. Here you can also ignore hard type validation if it is not necessary. Invalid numbers are ignored in the resulting array.\n\n```swift\nlet rawNumberArray = [\"0291 12345678\", \"+49 291 12345678\", \"04134 1234\", \"09123 12345\"]\nlet phoneNumbers = phoneNumberUtility.parse(rawNumberArray)\nlet phoneNumbersCustomDefaultRegion = phoneNumberUtility.parse(rawNumberArray, withRegion: \"DE\",  ignoreType: true)\n```\n\nPhoneNumber objects are immutable Swift structs with the following properties:\n\n```swift\nphoneNumber.numberString\nphoneNumber.countryCode\nphoneNumber.nationalNumber\nphoneNumber.numberExtension\nphoneNumber.type // e.g Mobile or Fixed\n```\n\nFormatting a PhoneNumber object into a string is also very easy\n\n```swift\nphoneNumberUtility.format(phoneNumber, toType: .e164) // +61236618300\nphoneNumberUtility.format(phoneNumber, toType: .international) // +61 2 3661 8300\nphoneNumberUtility.format(phoneNumber, toType: .national) // (02) 3661 8300\n```\n\n## PhoneNumberTextField\n\n![AsYouTypeFormatter](https://user-images.githubusercontent.com/7651280/67554038-e6512500-f751-11e9-93c9-9111e899a2ef.gif)\n\nTo use the AsYouTypeFormatter, just replace your UITextField with a PhoneNumberTextField (if you are using Interface Builder make sure the module field is set to PhoneNumberKit).\n\nYou can customize your TextField UI in the following ways\n\n- `withFlag` will display the country code for the `currentRegion`. The `flagButton` is displayed in the `leftView` of the text field with it's size set based off your text size.\n- `withExamplePlaceholder` uses `attributedPlaceholder` to show an example number for the `currentRegion`. In addition when `withPrefix` is set, the country code's prefix will automatically be inserted and removed when editing changes.\n\nPhoneNumberTextField automatically formats phone numbers and gives the user full editing capabilities. If you want to customize you can use the PartialFormatter directly. The default region code is automatically computed but can be overridden if needed (see the example given below).\n\n```swift\nclass MyGBTextField: PhoneNumberTextField {\n    override var defaultRegion: String {\n        get {\n            return \"GB\"\n        }\n        set {} // exists for backward compatibility\n    }\n}\n```\n\n```swift\nlet textField = PhoneNumberTextField()\n\nPartialFormatter().formatPartial(\"+336895555\") // +33 6 89 55 55\n```\n\nYou can also query countries for a dialing code or the dialing code for a given country\n\n```swift\nphoneNumberUtility.countries(withCode: 33)\nphoneNumberUtility.countryCode(for: \"FR\")\n```\n\n## Customize Country Picker\n\nYou can customize colors and fonts on the Country Picker View Controller by overriding the property \"withDefaultPickerUIOptions\"\n\n```swift\nlet options = CountryCodePickerOptions(\n    backgroundColor: UIColor.systemGroupedBackground\n    separatorColor: UIColor.opaqueSeparator\n    textLabelColor: UIColor.label\n    textLabelFont: .preferredFont(forTextStyle: .callout)\n    detailTextLabelColor: UIColor.secondaryLabel\n    detailTextLabelFont: .preferredFont(forTextStyle: .body)\n    tintColor: UIView().tintColor\n    cellBackgroundColor: UIColor.secondarySystemGroupedBackground\n    cellBackgroundColorSelection: UIColor.tertiarySystemGroupedBackground\n)\ntextField.withDefaultPickerUIOptions = options\n```\n\nOr you can change it directly:\n\n```swift\ntextField.withDefaultPickerUIOptions.backgroundColor = .red\n```\n\nPlease refer to `CountryCodePickerOptions` for more information about usage and how it affects the view. \n\n\n## Need more customization?\n\nYou can access the metadata powering PhoneNumberKit yourself, this enables you to program any behaviours as they may be implemented in PhoneNumberKit itself. It does mean you are exposed to the less polished interface of the underlying file format. If you program something you find useful please push it upstream!\n\n```swift\nphoneNumberUtility.metadata(for: \"AU\")?.mobile?.exampleNumber // 412345678\n```\n\n### [Preferred] Setting up with [Swift Package Manager](https://swiftpm.co/?query=PhoneNumberKit)\n\nThe [Swift Package Manager](https://swift.org/package-manager/) is now the preferred tool for distributing PhoneNumberKit. \n\nFrom Xcode 11+ :\n\n1. Select File \u003e Swift Packages \u003e Add Package Dependency. Enter `https://github.com/marmelroy/PhoneNumberKit.git` in the \"Choose Package Repository\" dialog.\n2. In the next page, specify the version resolving rule as \"Up to Next Major\" from \"4.0.0\".\n3. After Xcode checked out the source and resolving the version, you can choose the \"PhoneNumberKit\" library and add it to your app target.\n\nFor more info, read [Adding Package Dependencies to Your App](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app) from Apple.\n\nAlternatively, you can also add PhoneNumberKit to your `Package.swift` file:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/marmelroy/PhoneNumberKit\", from: \"4.0.0\")\n]\n```\n\n### Setting up with Carthage\n\n[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that automates the process of adding frameworks to your Cocoa application.\n\nYou can install Carthage with [Homebrew](http://brew.sh/) using the following command:\n\n```bash\n$ brew update\n$ brew install carthage\n```\n\nTo integrate PhoneNumberKit into your Xcode project using Carthage, specify it in your `Cartfile`:\n\n```ogdl\ngithub \"marmelroy/PhoneNumberKit\"\n```\n\n### Setting up with [CocoaPods](http://cocoapods.org/?q=PhoneNumberKit)\n\n```ruby\npod 'PhoneNumberKit', '~\u003e 4.0'\n```\n","funding_links":[],"categories":["Libs","Swift","UI","Text","Validation [🔝](#readme)","Screen Layout Programmatically"],"sub_categories":["Validation","Layout","Other free courses","Other Testing","Text","Keychain","MVC vs MVVM"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarmelroy%2FPhoneNumberKit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarmelroy%2FPhoneNumberKit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarmelroy%2FPhoneNumberKit/lists"}