Options

Mask

Element masks enable user input to be restricted and formatted to meet a pre-defined format. A mask can be defined programmatically using the ElementMask class, or in an XML layout file as a pattern String.

<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">

  <com.basistheory.android.view.TextElement
      android:id="@+id/masked_value"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      app:bt_mask="###-##-####" />

</layout>

When setting a mask programmatically, the ElementMask class supports two constructors:

1. ElementMask(characterMasks: List<Any>): a list of character-wise values defining the allowable input for each character position. Each character position either defines a static value in the mask (specified as a Char or single character String) or a range of allowable characters (specified as a Regex object).

For example, to support US Social Security Numbers of the form 123-45-6789, you can specify the mask as:

val digit = Regex("""\d""")
element.mask = ElementMask(listOf(digit, digit, digit, "-", digit, digit, "-", digit, digit, digit, digit))

2. ElementMask(pattern: String): specifies a range of allowable characters using the wildcard characters:
   • #: numeric value, equivalent to Regex("""\d""")
   • x: alphabetic value, equivalent to Regex("[A-Za-z]")
   • *: any value, equivalent to Regex(".")

For example, to support US Social Security Numbers of the form 123-45-6789, you can specify the mask as:

element.mask = ElementMask("###-##-####")

Transform

Element transforms define functions that mutate the value of the element prior to tokenization and when computing properties published within ChangeEvents.

The following types of transforms are supported:

RegexReplaceElementTransform

Replaces all matches of the given regular expression with the replacement text.

// removes all non-numeric characters
element.transform = RegexReplaceElementTransform(
    regex = Regex("[^\\d]"),
    replacement = ""
)

Validator

Element validators define functions to determine whether the value of the Element is considered valid. Validators are executed on the transformed Element value.

The validation state of an Element is only used when computing ChangeEvents and all invalid state behavior (e.g. styling changes, displaying validation errors, disabling submit buttons) are expected to be implemented within your application in response to ChangeEvents.

The following types of validators are supported:

RegexValidator

Matches the input value against the given regular expression.

// validates that the value only contains 3-4 digits
element.validator = RegexValidator(
    regex = Regex("^\\d{3,4}$")
)

LuhnValidator

Validates that the input value is a Luhn-valid credit card number. This is the default validator for the CardNumberElement.

element.validator = LuhnValidator()

FutureDateValidator

Validates that the input value is a future date of the form MM/yy. This is the default validator for the CardExpirationDateElement.

element.validator = FutureDateValidator()

Input Types

All Elements expose an inputType property to indicate the content type of the Element. This property can be set via XML using the android:inputType attribute. This property can be used to control the virtual keyboard type displayed while editing an Element and also whether data entered into an Element will be displayed or hidden (replaced with dots) on the device's screen.

Enum Value	XML Attribute Value	Keyboard Type	Display Format
TEXT	text	Alphanumeric	Plaintext
NUMBER	number	Numeric	Plaintext
TEXT_PASSWORD	textPassword	Alphanumeric	Hidden
NUMBER_PASSWORD	numberPassword	Numeric	Hidden

Get Value Type

The getValueType attribute allows you to specify the type of value that will be rendered when the Element is sent to the API. If none is specified, the value will be rendered as a String. The following types are supported:

getValueType Value	Type
ElementValueType.STRING	String
ElementValueType.INTEGER	Int
ElementValueType.DOUBLE	Double
ElementValueType.BOOLEAN	Boolean

element.getValueType = ElementValueType.INTEGER

Enable Copy

Enable Copy allows users to copy the value of the Element to their clipboard without the implementer touching the data.

A copy icon is added to the right side of the input field through the enableCopy attribute. The icon can be tapped to copy the Element value to the clipboard. The icon will change to a checkmark when the value has been copied and change back to the copy icon after a brief moment.

element.enableCopy = true

Copy Icon Color

The color of the icon can be changed from the default black through the copyIconColor attribute. That attribute takes in a int value. For example, to change the color to red, you can do the following:

element.copyIconColor = Color.RED

The android.graphics package has a number of color constants that can be used, but you can use any custom colors by encoding them as integers.

Styling

Elements have been designed to take advantage of all pre-existing native layout properties available on a FrameLayout, as well as several additional styling customizations typically available to a native EditText view.

Styling in XML

<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <com.basistheory.android.TextElement
        android:id="@+id/my_text_element"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:background="@drawable/my_custom_background"
        android:padding="5dp"
        android:text="Initial Value"
        android:hint="Placeholder"
        android:textColor="@color/my_color"
        android:typeface="sans" 
        android:gravity="center" />

</layout>

See TextElement for an exhaustive list of supported XML attributes.

Styling Programmatically

val textElement = binding.myTextElement // or findViewById<TextElement>(R.id.my_text_element)
textElement.setPadding(5, 5, 5, 5)
textElement.hint = "Placeholder"
textElement.textColor = Color.CYAN
textElement.background = Color.WHITE.toDrawable()
textElement.typeface = getFont(requireContext(), R.font.my_custom_font)
textElement.gravity = Gravity.CENTER

See TextElement for an exhaustive list of supported properties.