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

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" />

</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)

See TextElement for an exhaustive list of supported properties.