☕️ Android Aroma Pincode

The Android Aroma Pincode package provides a highly customisable pincode view. This README describes how to implement the Pincode component into an app.

This GitHub repository is a mirror, the official repository is hosted privately by Coffee IT.

Created by Coffee IT.

⚡ Installation

This component requires minimum SDK 21.

Add the dependency to build.gradle.

Groovy:

dependencies {
    implementation "nl.coffeeit.aroma:pincode:1.0.3"
}

KTS:

dependencies {
    implementation("nl.coffeeit.aroma:pincode:1.0.3")
}

📖 Usage

To use the component as in a Compose project, simply add it to your code as is. This example showcases a simple version:

PincodeView(
    pincodeLiveData = pincode,
    isErrorLiveData = isError,
    enableSendButton = true,
    onPincodeCompleted = {
        // Pin code filled in
    },
    onSend = {
        // Send button clicked
    }
)

To use the component as part of a XML-based project, add a ComposeView element to your layout file and call the setContent method in your activity/fragment:

lateinit var binding: ActivityMainBinding
    private val isError = MutableLiveData(false)
    private val pincode = MutableLiveData("")

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = DataBindingUtil.setContentView(this, R.layout.activity_main)

        binding.cvPincode.setContent {
            PincodeView(pincodeLiveData = pincode, isErrorLiveData = isError)
        }
    }

⚙️ Customisation

PincodeView accepts the following optional parameters for in depth customisation:

• lengthOfCode - An integer that decides the length of the pincode (default 6)
• inputWidth - Dp object to set width of each input cell
• inputCornerShape - RoundedCornerShape object to set rounded corners on the input cells
  • Example: RoundedCornerShape(12.dp)
• inputColors - TextFieldColors object to determine the colors in and around the input cells
• inputSpacing - Dp object to set the spacing betweens each input cell
• showDividerAfterInput - decides after how many cells a divider should be shown
• dividerColor - the color of the divider
• dividerHeight - the height of the divider in Dp
• errorText - shown text when the component is in an error state
• errorLabelPaddingVertical - the vertical padding of the error label in Dp
• focusedBorderThickness - border thickness of the cells when focused
• unfocusedBorderThickness - border thickness of the cells when not focused
• inputTextStyle - TextStyle object to determine the text style of inputs
• inputErrorTextStyle - TextStyle object to determine the text style of inputs when in error state
• errorLabelTextStyle - TextStyle object to determine the text style of the error label
• sendButtonTextStyle - TextStyle object to determine the text style of the send button
• sendButtonDisabledTextStyle - TextStyle object to determine the text style of the error label when disabled
• onlyDigits - Boolean to make the component accept only digits
• autoFocusFirstInput - Boolean to make the component focus the first input automatically
• resetPincodeLiveData - Unit that runs when the Pincode LiveData gets reset
• onBack - Unit that runs when the back button is pressed
• onPincodeCompleted - Unit that runs when all cells are filled in
• enableSendButton - Enables the send button
• sendButtonConfiguration - SendButtonConfiguration
  • Example: SendButtonConfiguration(text = "Send code", cornerShape = RoundedCornerShape(12.Dp), alignment = ButtonPosition.START
• sendButtonConfigurationDisabled - SendButtonConfiguration when send button is disabled
• sendCooldownDuration - integer in seconds, to determine how long the send button should be disabled for when clicked
• onSend - Unit that runs when the send button is clicked
• pincodeLiveData - LiveData object of a String. This Object will be updated to reflect the Pincode characters in the UI.
• isErrorLiveData LiveData object of a Boolean. This Boolean determines whether the Pincode view is in an error state or not.
• sendCodeLiveData - LiveData object of a Boolean. When this Boolean is set to true onSend is triggered, the timer starts counting down and the send button gets disabled. Should be set to false to be able to use it again.
• keyEventInErrorState - Unit that runs when a key is pressed while the component is in an error state

✏️ Changelog

The changelog can be found here.

🔗 Related publications

• Aroma Pincode Component for iOS

Look at our other repositories on our GitHub account.

📧 Contact

Do you have questions, ideas or need help? Send us an email at contact@coffeeit.nl.

⚠️ License

Android Aroma Pincode is licensed under the terms of the MIT Open Source license.