Elements are secure, iframed inputs that keep you in PCI SAQ A while giving you complete design control. Create an Elements group, add card fields (combined or individual), and interact with them through a consistent JavaScript API.

Key details

Elements

Note – Using Hosted Fields?
Earlier Recurly.js versions rendered payment fields with Hosted Fields. That feature is now deprecated. We recommend upgrading to Elements; however, v4 retains backward-compatibility. See the v4.10.3 documentation for Hosted Fields details.

Elements allow sensitive customer payment information to be securely accepted via iframes. They are controlled in groups by an Elements instance.

To use Elements, you will first create an Elements instance.

const elements = recurly.Elements();

There are several types of Elements which you may wish to use. The most common is the CardElement.

const cardElement = elements.CardElement();

Recurly.js also provides individual card Elements.

const cardNumberElement = elements.CardNumberElement();
const cardMonthElement  = elements.CardMonthElement();
const cardYearElement   = elements.CardYearElement();
const cardCvvElement    = elements.CardCvvElement();

The reference below details the common API for interacting with Elements and Element instances. While you may be working with different Element types, their API is the same.

Reference

fn – recurly.Elements

Creates an Elements instance, which associates a group of Element instances for tokenization and control. You will use this to create individual Element instances.

const elements = recurly.Elements();

Returns

A new Elements instance.

event – Emits

See Events for usage.

Event name	Payload	Occurs when
submit	—	A user presses `Enter` while using an `Element` created with the `Elements` instance.

fn – elements.CardElement

fn – elements.CardNumberElement

fn – elements.CardMonthElement

fn – elements.CardYearElement

fn – elements.CardCvvElement

Create an Element instance of the type respective of its name.

const cardElement = elements.CardElement({
  style: {
    fontSize: '2em'
  }
});

Arguments

Param	Type	Description
`options`	Object
`options.inputType`	String	See Styling Elements
`options.style`	Object	See Styling Elements

Returns

A new Element instance.

event – Emits

See Events for usage.

Event name	Payload	Occurs when
change	`ElementState`	The Element state changes.
focus	—	A user focuses on the Element.
blur	—	A user removes focus from the Element.
submit	—	A user presses `Enter` while using the Element.
attach	—	The Element has completed attaching to the DOM.
remove	—	The Element has been removed from the DOM.
coBadge	`CoBadgeResults`	The user enters a valid card number.

fn – Element.attach

Attaches an Element to the DOM as a child of the specified parent target.

element.attach('#my-element-container');

Arguments

Param	Type	Description
`parent`	`HTMLElement` or `String`	Target element (or selector) not being a void HTML element.

Returns

The Element instance.

fn – Element.configure

Updates the configuration of the Element.

element.configure({
  style: { fontSize: '2em' }
});

Arguments

Param	Type	Description
`options`	Object
`options.inputType`	String	See Styling Elements
`options.style`	Object	See Styling Elements

Returns

The Element instance.

fn – Element.focus

Moves the user's focus to the Element.

Safari allows programmatic focus only after prior user interaction.

Returns

The Element instance.

fn – Element.remove

If attached, removes the Element from the DOM; otherwise does nothing.

Returns

The Element instance.