Skip to main content

iOS Elements SDK

iOS Elements SDK


Basis Theory iOS Elements are simple, secure, developer-friendly inputs that empower consumers to collect sensitive data from their users directly to Basis Theory's certified vault.

Think about it as an isolated sandbox within your mobile application that your end users are able to seamlessly interact with, and which securely communicates with the Basis Theory Vault. Sensitive data is not directly exposed to your application code, which keeps your mobile application out of compliance scope.

Here's how we make this possible:

  • Install our iOS SDK into your mobile application
  • Build forms using our Element input components
  • Interact with the Basis Theory API using Element references, not plaintext data
  • Own your UI/UX by fully customizing how Elements are styled

Collect Sensitive Data

Data entered by your end users into iOS Elements is tokenized and secured within Basis Theory's certified Vault.

Our SDKs provide several types of inputs to collect various types of data, such as the TextElementUITextField for collecting arbitrary textual data and CardNumberUITextField for collecting a credit card number.

Elements can be configured to support custom input masking, validation, and transformation rules to satisfy your use cases.

Reveal Sensitive Data

Tokens stored within the Basis Theory Vault can be securely revealed to end users without accessing the plaintext data directly within your application code.

The ability to reveal sensitive data on iOS is not yet generally available. If you are interested in using this feature on iOS, please email us at to join our early access program.

Before You Begin

Basis Theory iOS Elements require the use of an API Key associated with a Public Application, which only allows token:create and token:update permissions to mitigate the risk that these API keys may be publicly exposed within your frontend applications.

To create one, login into our Portal and create a new "Public" Application with the permissions you require.


Add the Basis Theory iOS package using Swift Package Manager via XCode. To do this, follow these steps.

  1. Via File -> Add Packages, search for "" and click on "Copy Dependency".

  2. Add the following line under dependencies to Package.swift.

.package(url: "", from: "X.X.X")
  1. Then, add BasisTheoryElements as a dependency to your target.
dependencies: [
.product(name: "BasisTheoryElements", package: "basistheory-ios"),
  1. Add the following line to your Podfile under your target.
pod 'BasisTheoryElements'


To initialize our elements, you’ll need to set a custom class on each of the UITextFields that need to be configured as one of our secure elements. Below is an example of a UITextField set as TextElementUITextField.

Below is an example of a UITextField set as TextElementUITextField.

Styling Elements

All of our elements have been designed to take advantage of the pre-existing native properties and customizations built directly into the UIKit framework. Utilizing this framework means you’re able to customize the styling of your elements as you would with any other UITextField. For example:

@IBOutlet weak var myTextElement: TextElementUITextField!

myTextElement.layer.cornerRadius = 15.0
myTextElement.placeholder = placeholder
myTextElement.backgroundColor = UIColor( red: 240/255, green: 240/255, blue: 240/255, alpha: 1.0 )

Modified and Additional Fields

BasisTheoryElements package’s elements are a simple wrapper for the native UIKit UITextField. Due to this developers can take full advantage of existing native customization, but we restrict and enable access to the underlying data in the following ways:

textWe restrict the getter for this value; it always returns nil. The setter works as is.
subjectAn instance of PassThroughSubject that allows you to subscribe to ElementEvents.
setValueA function that recieves an ElementValueReference parameter to set the value of the element. Note: ElementValueReference instances can only be retrieved from proxy responses.
setValueRefBinds the provided element instance as a value source for the calling element, keeping the value of the calling element in sync with any changes made to the provided element. This makes the caller element read-only. Any iOS element type can be provided as an instance into this function.
setConfigA function that allows you to set a mask and transform on TextElementUITextField's, and associate a CardNumberUITextField to a CardVerificationCodeUITextField.
metadataAn object that contains metadata about the element state in regards to its value.
cardMetadataAn object that contains metadata about the card number for the CardNumberUITextField element type only.