diff --git a/docs/sdks/web/javascript/methods.mdx b/docs/sdks/web/javascript/methods.mdx
index 695aa6fe..c47a3054 100644
--- a/docs/sdks/web/javascript/methods.mdx
+++ b/docs/sdks/web/javascript/methods.mdx
@@ -2,9 +2,9 @@
sidebar_label: Methods & Events
---
-import {Alert, Alerts} from "@site/src/components/shared/Alert";
+import { Alert, Alerts } from "@site/src/components/shared/Alert";
-# Elements Method & Events
+# Elements Methods & Events
Basis Theory Elements offers several methods and events to listen to changes to your components and interact with the underlying data.
@@ -77,16 +77,25 @@ cardElement.on("change", (changeEvent) => {
#### ChangeEvent
+`ChangeEvent`s are emitted depending on the validation strategy set for each element; by default, validations run `onBlur`. You can change this behavior by setting the boolean flag [`validateOnChange`](/docs/sdks/web/javascript/options) to `true`.
+
+When running validations onChange, elements emit events
+whenever an error occurs or if the input's value
+changes. Default validation (`onBlur`) triggers an event every time one of the values below changes:
+
```json showLineNumbers
{
"complete": false,
+ "valid": false,
+ "maskSatisfid": false,
"empty": false,
"errors": [
{...},
{...}
],
"cardBrand": "american-express",
- "cardLast4": "8431"
+ "cardLast4": "8431",
+ "cardBin": "341212"
}
```
diff --git a/docs/sdks/web/javascript/options.mdx b/docs/sdks/web/javascript/options.mdx
index 1497c999..9443317f 100644
--- a/docs/sdks/web/javascript/options.mdx
+++ b/docs/sdks/web/javascript/options.mdx
@@ -9,20 +9,40 @@ import CardBrands from "@site/docs/sdks/_card-brands.mdx";
You can customize the behavior of your Elements using the following options:
-| Attribute | Required | Type | Updatable | Eligible Elements | Description |
-|----------------|----------|-----------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `style` | false | _object_ | true | All | [Object](#style) used to customize the element appearance |
-| `disabled` | false | _boolean_ | true | All | Boolean used to set the [disabled attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled) of the input(s) |
-| `autoComplete` | false | _string_ | true | All | String used to set the [autocomplete attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) of the input(s). Expected values are: `off` (default), or `on`. |
-| `targetId` | true | _string_ | false | [`text`](/docs/sdks/web/javascript/types#text-element)
[`cardNumber`](/docs/sdks/web/javascript/types#card-number-element)
[`cardExpirationDate`](/docs/sdks/web/javascript/types#card-expiration-date-element)
[`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | String used to identify your element |
-| `placeholder` | false | _string_ | true | [`text`](/docs/sdks/web/javascript/types#text-element)
[`cardNumber`](/docs/sdks/web/javascript/types#card-number-element)
[`cardExpirationDate`](/docs/sdks/web/javascript/types#card-expiration-date-element)
[`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | String used to customize the [placeholder attribute](https://developer.mozilla.org/docs/Web/HTML/Element/input#attr-placeholder) of the input |
-| `aria-label` | false | _string_ | true | [`text`](/docs/sdks/web/javascript/types#text-element)
[`cardNumber`](/docs/sdks/web/javascript/types#ard-number-element)
[`cardExpirationDate`](/docs/sdks/web/javascript/types#card-expiration-date-element)
[`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | String used to customize the [aria-label attribute](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) of the input |
-| `mask` | false | _array_ | false | [`text`](/docs/sdks/web/javascript/types#text-element) | [Array](#mask) used to restrict and fill user input using regex and static strings |
-| `transform` | false | _RegExp_ | true | [`text`](/docs/sdks/web/javascript/types#text-element) | [`RegExp` object or array](#transform) used to modify user input before [tokenization](/docs/sdks/web/javascript/methods#tokenization) |
-| `password` | false | _boolean_ | true | [`text`](/docs/sdks/web/javascript/types#text-element) | Boolean used to set the text element input type as [password](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password) |
-| `iconPosition` | false | _string_ | true | [`cardNumber`](/docs/sdks/web/javascript/types#card-number-element) | String used to determine the position of the card element icon. Expected values are: `left` (default), `right` or `none`. |
-| `cardBrand` | false | _string_ | true | [`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | [Brand identifier](#card-brands) used to determine proper input format and default placeholder/aria-label |
-| `value` | false | _string_ | true | All | Sets a static value for the element input. |
+| Attribute | Required | Type | Updatable | Eligible Elements | Description |
+| ------------------ | -------- | --------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `style` | false | _object_ | true | All | [Object](#style) used to customize the element appearance |
+| `disabled` | false | _boolean_ | true | All | Boolean used to set the [disabled attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled) of the input(s) |
+| `autoComplete` | false | _string_ | true | All | String used to set the [autocomplete attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) of the input(s). Expected values are: `off` (default), or `on`. |
+| `targetId` | true | _string_ | false | [`text`](/docs/sdks/web/javascript/types#text-element)
[`cardNumber`](/docs/sdks/web/javascript/types#card-number-element)
[`cardExpirationDate`](/docs/sdks/web/javascript/types#card-expiration-date-element)
[`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | String used to identify your element |
+| `placeholder` | false | _string_ | true | [`text`](/docs/sdks/web/javascript/types#text-element)
[`cardNumber`](/docs/sdks/web/javascript/types#card-number-element)
[`cardExpirationDate`](/docs/sdks/web/javascript/types#card-expiration-date-element)
[`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | String used to customize the [placeholder attribute](https://developer.mozilla.org/docs/Web/HTML/Element/input#attr-placeholder) of the input |
+| `aria-label` | false | _string_ | true | [`text`](/docs/sdks/web/javascript/types#text-element)
[`cardNumber`](/docs/sdks/web/javascript/types#ard-number-element)
[`cardExpirationDate`](/docs/sdks/web/javascript/types#card-expiration-date-element)
[`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | String used to customize the [aria-label attribute](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) of the input |
+| `mask` | false | _array_ | false | [`text`](/docs/sdks/web/javascript/types#text-element) | [Array](#mask) used to restrict and fill user input using regex and static strings |
+| `transform` | false | _RegExp_ | true | [`text`](/docs/sdks/web/javascript/types#text-element) | [`RegExp` object or array](#transform) used to modify user input before [tokenization](/docs/sdks/web/javascript/methods#tokenization) |
+| `password` | false | _boolean_ | true | [`text`](/docs/sdks/web/javascript/types#text-element) | Boolean used to set the text element input type as [password](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password) |
+| `iconPosition` | false | _string_ | true | [`cardNumber`](/docs/sdks/web/javascript/types#card-number-element) | String used to determine the position of the card element icon. Expected values are: `left` (default), `right` or `none`. |
+| `cardBrand` | false | _string_ | true | [`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | [Brand identifier](#card-brands) used to determine proper input format and default placeholder/aria-label |
+| `validateOnChange` | false | _string_ | false | [`cardNumber`](/docs/sdks/web/javascript/types#ard-number-element)
[`cardExpirationDate`](/docs/sdks/web/javascript/types#card-expiration-date-element)
[`cardElement`](/docs/sdks/web/javascript/types#card-element)
[`cardVerificationCode`](/docs/sdks/web/javascript/types#card-verification-code-element) | Switches from default validation `onBlur` to `onChange`. |
+| `value` | false | _string_ | true | All | Sets a static value for the element input. |
+
+
+ Switching the validation strategy from onBlur to{" "}
+ onChange will change the sequence and increase the number of
+ events. When running validations onChange, elements emit events
+ whenever an error occurs or if the input's value{" "}
+ changes. Default validation onBlur triggers an event every time
+ one of the properties in the{" "}
+
+ changeEvent
+ {" "}
+ changes.
+
+
+
+ When using some end-to-end testing frameworks and using the default validation{" "}
+ onBlur, you may need to force the blur events to trigger the
+ validation due to framework-specific limitations.
+
The mask option cannot be used when the password{" "}
@@ -73,7 +93,7 @@ var cardElement = BasisTheory.createElement("card", {
```
| Attribute | Required | Type | Description |
-|------------|----------|----------|------------------------------------------------------------------------------------|
+| ---------- | -------- | -------- | ---------------------------------------------------------------------------------- |
| `fonts` | false | _array_ | Array of Google Fonts URLs |
| `base` | false | _object_ | Base variant style - all other variant styles inherit from this one |
| `complete` | false | _object_ | Variant style applied when the element input is complete |
@@ -215,7 +235,21 @@ before [tokenization](/docs/sdks/web/javascript/methods#tokenization).
```javascript showLineNumbers
var phoneNumberElement = BasisTheory.createElement("text", {
targetId: "myPhoneNumberElement",
- mask: ["(", /\d/, /\d/, /\d/, ")", /\d/, /\d/, /\d/, "-", /\d/, /\d/, /\d/, /\d/]
+ mask: [
+ "(",
+ /\d/,
+ /\d/,
+ /\d/,
+ ")",
+ /\d/,
+ /\d/,
+ /\d/,
+ "-",
+ /\d/,
+ /\d/,
+ /\d/,
+ /\d/,
+ ],
});
```
@@ -246,7 +280,21 @@ attribute, in this case, will modify the user input to remove `(`, `)`, and `-`
```javascript showLineNumbers
var phoneNumberElement = BasisTheory.createElement("text", {
targetId: "myPhoneNumberElement",
- mask: ["(", /\d/, /\d/, /\d/, ")", /\d/, /\d/, /\d/, "-", /\d/, /\d/, /\d/, /\d/],
+ mask: [
+ "(",
+ /\d/,
+ /\d/,
+ /\d/,
+ ")",
+ /\d/,
+ /\d/,
+ /\d/,
+ "-",
+ /\d/,
+ /\d/,
+ /\d/,
+ /\d/,
+ ],
transform: /[()-]/,
});
```