search

arpitkatiyar1999 / Country-Picker

Jetpack Compose Country Code Picker
Apache License 2.0
9 stars 2 forks source link
android-country-code-picker android-country-picker android-library compose compose-library country-code-picker country-picker countrycodepicker countrypicker jetpack jetpack-compose jetpack-compose-library kotlin kotlin-library library material3 material3-country-code-picker

readme

Jetpack Compose Country Code Picker

Jetpack Compose Country Code Picker is a simple, lightweight library built for Android using Jetpack Compose, designed to provide an easy-to-use country code selection functionality within your Android app. It seamlessly integrates with Material 3 design principles, offering a modern and consistent user experience. It effortlessly adapts to your application's theme, facilitating seamless integration with the visual identity of your application.

Platform   API Level   License     Language

Preview

CountryPicker
CountryPickerOutlinedTextField

Requirement

Jetpack Compose Country Code Picker requires Material 3 version 1.2.1 or later to work properly. To ensure compatibility, please make sure your project includes Material 3 version 1.2.1 or later.

If you are using the Compose BOM to manage dependencies, you can check your current Material 3 version by referring to the Compose BOM mapping.

Installation

Step 1: Add the JitPack repository to your build file

Add it in your settings.gradle file at the end of repositories:

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven(url = "https://jitpack.io")
  }
}

Step 2: Add the dependency

Add it in your build.gradle (module level) file:

dependencies {
  implementation("com.github.arpitkatiyar1999:Country-Picker:<latest-version>")
}

Overview

This library provides two composable functions for country code selection:

  1. CountryPicker: This function displays the country picker without any text field.
@Composable
fun CountryPicker(
  modifier: Modifier = Modifier,
  defaultPaddingValues: PaddingValues = PaddingValues(4.dp, 6.dp),
  selectedCountryDisplayProperties: SelectedCountryDisplayProperties = SelectedCountryDisplayProperties(),
  countriesListDialogDisplayProperties: CountriesListDialogDisplayProperties = CountriesListDialogDisplayProperties(),
  defaultCountryCode: String? = null,
  countriesList: List<String>? = null,
  onCountrySelected: (country: CountryDetails) -> Unit
)
Parameters
  1. CountryPickerOutlinedTextField: This function displays the country picker with outlined text field.
@Composable
fun CountryPickerOutlinedTextField(
  mobileNumber: String,
  onMobileNumberChange: (String) -> Unit,
  onCountrySelected: (country: CountryDetails) -> Unit,
  modifier: Modifier = Modifier,
  defaultPaddingValues: PaddingValues = PaddingValues(4.dp, 6.dp),
  selectedCountryDisplayProperties: SelectedCountryDisplayProperties = SelectedCountryDisplayProperties(),
  countriesListDialogDisplayProperties: CountriesListDialogDisplayProperties = CountriesListDialogDisplayProperties(),
  defaultCountryCode: String? = null,
  countriesList: List<String>? = null,
  enabled: Boolean = true,
  readOnly: Boolean = false,
  textStyle: TextStyle = LocalTextStyle.current,
  label: @Composable (() -> Unit)? = null,
  placeholder: @Composable (() -> Unit)? = null,
  trailingIcon: @Composable (() -> Unit)? = null,
  prefix: @Composable (() -> Unit)? = null,
  suffix: @Composable (() -> Unit)? = null,
  supportingText: @Composable (() -> Unit)? = null,
  isError: Boolean = false,
  visualTransformation: VisualTransformation = VisualTransformation.None,
  singleLine: Boolean = false,
  maxLines: Int = if (singleLine) 1 else Int.MAX_VALUE,
  minLines: Int = 1,
  interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
  shape: Shape = RoundedCornerShape(12.dp),
  colors: TextFieldColors = OutlinedTextFieldDefaults.colors(),
  borderThickness: BorderThickness = BorderThickness(),
  onDone: (() -> Unit)? = null,
)
Parameters

Helper Functions

Function Description Parameters
isMobileNumberValid(mobileNumber: String, countryCode: String) : Boolean Validates a mobile number based on the provided country code. mobileNumber : The mobile number to validate, which should not include the country’s phone code at the beginning.
countryCode : The country code for validating the mobile number.
getExampleMobileNumber(countryCode: String, formatNumber: Boolean = false): String Retrieves an example mobile number for a given country code, optionally formatted. countryCode : The country code for which the example mobile number is to be generated.
formatNumber : A boolean value (default is false). If true, the number will be formatted, otherwise, it will be raw.
getFormattedMobileNumber(mobileNumber: String, countryCode: String): String Formats a mobile number according to the country’s specific mobile number format, based on the provided country code. This function should only be invoked after ensuring that the mobile number is valid.. mobileNumber : The raw mobile number that needs to be formatted.
countryCode : The country code that defines the formatting rules for the mobile number.

Note: For all the above functions, the country code must follow the 2-letter ISO standard (e.g., "IN" for India). For a full list of country codes, please refer to the ISO 3166-1 alpha-2 country codes Wikipedia page.

Example Usage

// Example for isMobileNumberValid
val isValid = CountryPickerUtils.isMobileNumberValid("8123456789", "IN")
println(isValid) // Output: true

// Example for getExampleMobileNumber
val exampleNumber = CountryPickerUtils.getExampleMobileNumber("IN")
println(exampleNumber) // Output: Example formatted number, like "81234 56789"

// Example for getFormattedMobileNumber
val formattedNumber = CountryPickerUtils.getFormattedMobileNumber("8123456789", "IN")
println(formattedNumber) // Output: Formatted number, like "81234 56789"

For detailed examples of implementing CountryPicker and CountryPickerOutlinedTextField:

Versioning Format

This library follows the Major.Minor.Patch versioning format:

Note: When updating the library, be cautious with major version updates, as they may introduce breaking changes and could be incompatible with previous versions.

Contributing

We welcome contributions to this project! Please follow these steps to get started:

  1. Fork the Repository: Click on the "Fork" button at the top of the repository page to create a copy under your GitHub account.

  2. Clone the Repository: Clone your forked repository to your local machine to start working on your changes.

  3. Create a New Branch: To keep your work organized, create a new branch for each contribution.

  4. Make Your Changes: Implement your changes and ensure they are tested and documented as needed.

  5. Commit and Push: Write clear and descriptive commit messages, then push your branch to your fork.

  6. Submit a Pull Request: Open a pull request (PR) from your branch in the forked repository to the master branch of the original repository. Include a clear description of your changes and reference any relevant issues.

Thank you for contributing!