One of the key benefits of Recurly is the ability to collect and tokenize a subscriber’s payment information. Hosted Fields, included with Recurly.js, have historically been the primary mechanisms used to accomplish this as they provide a secure way to capture payment information without ever exposing it to our customers’ systems, thus greatly reducing their PCI compliance burden.

Although Hosted Fields have been effective in fulfilling this objective for many years, the interface was limited and wasn’t conducive to modern web UIs. Today, Recurly is pleased to announce the launch of Recurly.js Elements: a new name, a new API paradigm, and the same secure benefits that you’ve enjoyed with Hosted Fields. Elements provide a completely revamped interface, built to empower you with enhanced flexibility and control.

Hosted Fields evolves into Elements

Control of Hosted Fields is provided through one monolithic interface in the Recurly.js instance. This one-to-one relationship between a Recurly.js instance and a group of Hosted Fields is particularly problematic when styling, configuring and listening to events specific to individual Hosted Fields, as you do not have direct access to them. As an example, when configuring a style property (e.g., font color) for a specific Hosted Field (e.g., a card number field), the entire configuration block that controls all Hosted Fields has to be passed back into the Recurly.js instance. This often requires you to maintain a copy of the entire configuration state in order to update individual properties as needed. 

With Elements, we have decoupled the concept of Hosted Fields groups from the Recurly.js instance. Elements are exposed and instantiated directly, providing unobstructed access to all of the capabilities of the instance itself. The fundamental change is moving away from a one-to-one relationship between secure inputs to a one-to-many relationship between the main Recurly instance and Elements.

A closer look into Elements

Your Recurly.js instance is configured once with your Recurly public key, and then any number of Elements groups can be created and controlled individually, with the ability to attach or detach them from the DOM and style them directly. 

Another major improvement is the way events are emitted. Previously with Hosted Fields, events would be emitted to the Recurly.js top-level instance, then conditional logic would be applied to handle events for a specific field.

With Elements, event handlers can be attached to a specific element, eliminating the need for additional logic to determine the event's origin.

Paving the way for React and other technologies

The newly envisioned interface for our secure fields was created with consideration for how it would accommodate our future plans to provide support for React. The new tree-like structure enabled by Elements sets the stage for better management within the DOM tree, thus removing the need to resort to various workarounds when using React and similar technologies. 

Migrating from Hosted Fields to Elements

For more details and instructions on migrating from Hosted Fields to Elements, take a look at our documentation. Elements have been added to Recurly.js v4, so there’s no need for a major version upgrade.

If you’re not ready to migrate to Elements just yet, we’ve ensured that Recurly.js v4 maintains backward compatibility with Hosted Fields. However, all subsequent major versions of Recurly.js will position Elements as the sole interface into our secure fields. Thus, we encourage you to not delay in migrating to Elements.