Reference

Including element.js¶

However you’re using element.js, you always begin by including the library and setting your API key. To get started, include this script on your pages — it should always be loaded directly from https://js.liquido.com/element.js. For testing purposes, you can use https://js.dev.liquido.com/element.js.

<script src="https://js.liquido.com/element.js"></script>

The Liquido Object¶

liquido()
liquidoInstance.elements()
liquidoInstance.createToken()

Create an Liquido Instance¶

const liquidoInstance = liquido('your_api_key')

Create an elements Instance¶

Create pre-built UI components to collect payment information with Elements.

const elements = liquidoInstance.elements({ 
    locale: 'en',
    country: 'BR'
})

This method creates an instance of elements, which manages a group of Elements. It receives an options object. Available options are documented below:

Option	Type	Description
locale	String	The IETF language tag of the locale to display placeholders and error strings in. Default is Spanish (en). Supported values are: en, es, pt.
country	String	User’s country code. ISO 3166-1 alpha-2 codes.
fonts	Array (Optional)	An array of custom fonts, which Elements created from the elements object can use. Fonts can either be loaded via a CSS file by passing an object with the cssSrc attribute, or they can be loaded directly by passing a Font object.

cssSrc attribute¶

Parameter	Type	Description
cssSrc	String	A relative or absolute URL pointing to a CSS file with @font-face definitions.

The Font Object¶

Parameter	Type	Description
family	String	The name to give the font.
src	String	A valid src value pointing to your custom font file. This is usually (though not always) a link to a file with a .woff, .otf, or .svg suffix.
display	String(Optional)	A valid font-display value.
style	String	A valid font-style value. Defaults to 'normal'.
unicodeRange	String(Optional)	A valid unicode-range value.
weight	String(Optional)	A valid font-weight. Note that this is a string, not a number.

Create a card token¶

Use liquidoInstance.createToken to convert information collected by Elements into a token that you can safely pass to your server for use in an API call.

liquidoInstance.createToken(card, tokenData)
    .then((result) => {
      // Handle Token (result.data.cardId)
    })
    .catch((result) => {
      // Handle result.error
    })

This method has two arguments.

element, the Elements you wish to tokenize data from. If applicable, the Element pulls data from other Elements you’ve created on the same instance of elements to tokenize.
tokenData, an object containing additional payment information you might have collected. In the case of cards, it can contain any of the following parameters:

Parameter	Type	Description
name	String	Cardholder name.
email	String(Optional)	email address.

liquidoInstance.createToken returns a Promise which resolves with a result object. This object has either:

result.data: a Token was created successfully.
result.error: there was an error. This includes client-side validation errors.

result.data can contain any of the following parameters:

{
    "cardId": "3f4b0d0f-297e-4b2d-94f3-7e80e5d024e9",  // card token which need to send to server.
    "card": {                                          // card info
        "cardHolderName": "HolerName",                 // card holder name     
        "expirationMonth": 11,                       
        "expirationYear": 2026,
        "brand": "VISA",                        
        "bin": "411111",                               // Top 6 digits of card number
        "last4": "1111"                                // Last 4 digits of card number
    }
}

The Elements Object¶

elements.create()
element.mount()
element.addEvenetListener()
Other methods

elements.create(type, options)¶

const card = elements.create('card')

This method creates an instance of a specific Element. It takes the type of Elements to create as well as an options object.

Type	Description
card	A flexible single-line input that collects cardNumber, cardExpiration and cardCvc.
pan	The card‘s number. Use alongside the `expiration` and `cvv` Elements.
expiration	The card‘s expiration date. Use alongside the `pan` and `cvv` Elements.
cvv	The card‘s CVC number. Use alongside the `pan` and `expiration` Elements.

Examples Checkout¶

Example Checkout with card Element

Example Checkout with pan, expiration, and cvv Elements

Element Options¶

All Elements accept a common set of options.

Option	Type	Description
placeholder	String or Object	Set custom placeholder for Element. For `pan`, `expiration` or `cvv` Elements this option is a string with the corresponding placeholder value. If the Element is a `card` this option is an `object` with the corresponding placeholder value for each input: `{` `cvv: "cvv placeholder",` `pan: "number placeholder",` `expiration: "expiration placeholder"` `}`
classes	Object (Optional)	Set custom class names on the container DOM element when the Liquido Element is in a particular state. - `base` - The base class applied to the container. Defaults to LiquidoElement. - `complete`- The class name to apply when the Element is complete. Defaults to LiquidoElement--complete. - `empty` - The class name to apply when the Element is empty. Defaults to LiquidoElement--empty. - `focus` - The class name to apply when the Element is focused. Defaults to LiquidoElement--focus. - `invalid` - The class name to apply when the Element is invalid. Defaults to LiquidoElement--invalid.
style	Object (Optional)	Customize appearance using CSS properties. Style is specified as an object for any of the variants below. - `base`, base style - all other variants inherit from this style. - `complete`, applied when the Element has valid input. - `empty`, applied when the Element has no customer input. - `invalid`, applied when the Element has invalid input. For each of the above, the properties below can be customized. - `color` - `fontFamily` - `fontSize` - `fontStyle` - `lineHeight`, to avoid cursors being rendered inconsistently across browsers, consider using padding on the Element's container instead. - `letterSpacing` The following pseudo-classes and pseudo-elements can also be styled with the above properties, as a nested object inside the variant. - `:hover` - `:focus` - `::placeholder`

element.mount(domElement)¶

You need to create a container DOM element to mount an Element.

The element.mount() method attaches your Field to the DOM. element.mount() accepts either a CSS Selector (eg: '#card-element') or a DOM element.

card.mount('#form-item__card')

element.addEventListener(event, handler)¶

The only way to communicate with your Element is by listening to an event. Elements might emit any of the events below. All events have a payload object that has an element property with the type of the Element that emitted the event.

Event	Description
blur	Triggered when any of the elements loses focus. The event payload always contains certain keys: `empty` - Boolean - `true` if the value is empty. `complete` - Boolean - `true` if the value is well-formed and complete. --`complete` can be used to progressively disclose the next parts of your form or to enable form submission. --`complete` is not an indicator of whether a customer is done with their input — it only indicates that the Element contains a complete, well-formed value. `error` - The current validation error, if any. Comprised of `message`, `code`, and `element` set to `validation_error`. The error is returned only when the field is not empty and fails validation. `element` - String - The name of the field that triggered the event: `pan`, `expiration`, `cvv`. `hasFocus` - Boolean - `true` if any of the Elements has focus (always false in `pan`, `expiration` and `cvv` elements).
focus	Triggered when any of the elements gains focus. The event payload always contains certain keys: `empty` - Boolean - `true` if the value is empty. `complete` - Boolean - `true` if the value is well-formed and complete. --`complete` can be used to progressively disclose the next parts of your form or to enable form submission. --`complete` is not an indicator of whether a customer is done with their input — it only indicates that the Element contains a complete, well-formed value. `error` - The current validation error, if any. Comprised of `message`, `code`, and `element` set to `validation_error`. `element` - String - The name of the field that triggered the event: `pan`, `expiration`, `cvv`.
error	Triggered when a client-side validation `error` is detected. The event payload always contains an error key which contains the current validation error. Comprised of: `message`, `code` and `element`, set to `validation_error`.
complete	Triggered when the Element changes its complete status. The event payload always contains a `complete` - Boolean - key, which is `true` when the Element is complete and well-formed, and `false` otherwise.
empty	Triggered when the Element changes its empty status. The event payload always contains an `empty` - Boolean - key, which is `true` when the Element is empty, and `false` otherwise.
ready	Triggered when the Field is mounted and loaded in the DOM.
change	Triggered when any of the following values changes to the Element. The event payload always contains certain keys, in addition to some element-specific keys. `empty` - Boolean - `true` if the value is empty. `complete` - Boolean - `true` if the value is well-formed and complete. --`complete` can be used to progressively disclose the next parts of your form or to enable form submission. --`complete` is not an indicator of whether a customer is done with their input — it only indicates that the Element contains a complete, well-formed value. `error` - The current validation error, if any. Comprised of `message`, `code`, and `element` set to `validation_error`. The error is returned only when the field meets the required length but fails validation.

Error code (number)	Description
1	The component has not been mounted yet.
2	The component value is null.
3	The value of the component fails validation.

Since the error is returned conditionally, you can manually validate the component value using the complete and empty boolean flags, which are always included in each event.

Input validation¶

Elements validates customer input as it is typed. To help your customers catch mistakes, listen to change events on the Element and display any reported errors:

card.addEventListener('change', (event) => {
  var errorEl = document.getElementById('form-item__error--card')
  errorEl.textContent = event.error
      ? event.error.message
      : ''
})

Other Methods¶

Method	Description
blur()	Blurs the Element.
clear()	Clears the value(s) of the ELement.
destroy()	Removes the Element from the DOM and destroys it. Note: a destroyed Element cannot be re-activated or re-mounted to the DOM.
focus()	Focuses the Element. In a `card` Element it will focus on the `pan` field.
unmount()	Unmounts the Field from the DOM. Call `element.mount()` to re-attach it to the DOM.
update(options)	Updates the options the Elements was initialized with. Accepts the same options as `elements.create()`.

The styles of an Element can be dynamically changed using update(). This method can be used to simulate CSS media queries that automatically adjust the size of Elements when viewed on different devices.

window.addEventListener('resize', (event) => {
  if (window.innerWidth <= 320) {
    card.update({
        style: {
            base: {
                fontSize: '13px'
            }
         }
      })
  } else {
    card.update({
        style: {
            base: {
                fontSize: '16px'
            }
         }
     })
  }
})