---
updatedAt: 2025-10-02T17:03:32.000Z
agentTools:
siteIndex: https://docs.recurly.com/llms.txt
projectIndex: https://docs.recurly.com/recurly-subscriptions/llms.txt
---
# Upgrading
Step-by-step guidance for migrating legacy Recurly.js integrations—Hosted Fields, v3, and older—to modern v4 Elements.
Recurly.js v4 replaces legacy approaches with **Elements**, a flexible, iframe-based system that improves security, styling control, and future-proof access to features such as 3-D Secure, Apple Pay, and risk tools. This upgrade guide shows:
1. How to convert Hosted Fields configs to Elements.
2. What changes are required when moving from v3.
3. Why versions prior to v3 require a full re-implementation.
## Prerequisites and limitations
* **Site must already be on Recurly.js v4+** (Elements are not back-ported).
* **Token format unchanged** – existing server-side API calls continue to work once you pass the new token.
* Upgrading from v2 or earlier **necessitates a complete rewrite**; there is no drop-in shim.
# Key details
Upgrading from previous versions and deprecated features of Recurly.js
### Upgrading from Hosted Fields to Elements
Recurly.js `v4.11.0` introduced Elements, a new API for displaying and controlling UI components of Recurly.js. They fulfill all of the roles that Hosted Fields had -- to display credit card inputs on your payment pages. Elements bring a more flexible API for interacting with objects that render to your page. So while their main use-case will be to render card inputs, in the future they will also be used to interact with other UI components, like 3-D Secure challenges, Apple Pay, PayPal flows, price information, and risk/fraud detection.
Hosted Fields had exposed their interface through `recurly.configure`. In migrating to Elements, you will move this configuration to `Element` constructors:
**Setup changes**
*Old Hosted Field Setup*
```html
```
```js
recurly.configure({
publicKey: 'my-public-key',
fields: {
card: {
inputType: 'mobileSelect',
style: {
fontColor: '#010101'
}
}
}
});
```
*New Setup with Elements*
```html
```
```js
recurly.configure('my-public-key');
const elements = recurly.Elements();
const card = elements.CardElement({
style: {
inputType: 'mobileSelect',
fontColor: '#010101'
}
});
card.attach('.my-card-element');
```
**Changes to Event Listeners**
If you are listening for changes to Hosted Field using the `'change'` event, you will now listen for these changes on an `Element` instance.
*Old Hosted Field change listener*
```js
recurly.on('change', (state) => {
if (state.fields.card.focus) {
// Listen for focus on my card field
}
});
recurly.on('field:submit', () => {
// Listen for use pressing within a hosted field
});
```
*New Elements event listeners*
```js
const elements = recurly.Elements();
const card = elements.CardElement();
card.on('change', (state) => {
// Listen for any change to my Element
});
card.on('focus', (state) => {
// Listen for user focus on my Element
});
card.on('blur', (state) => {
// Listen for user blur on my Element
});
card.on('submit', () => {
// Listen for use pressing within an Element
});
```
See [Elements](https://docs.recurly.com/v1.2/docs/elements#/) for details on all events emitted by an `Element`.
**Changes to Getting a Token**
When creating a token from `Elements`, it is necessary to pass your `Elements` instance to `recurly.token` along with the form containing your user's billing information. This allows for the flexibility of creating many `Elements` on a single page, and improved specificity.
*Old Hosted Field token creation*
```js
const form = document.querySelector('#my-form');
recurly.token(form, (err, token) => {
// handle my new token
});
```
*New token creation with Elements*
```js
const elements = recurly.Elements();
const form = document.querySelector('#my-form');
// create and attach my Element instances
recurly.token(elements, form, (err, token) => {
// handle my new token
});
```
We are happy to assist further in your upgrade path. Feel free to reach out to us for [Support](https://support.recurly.com/hc/en-us).
### Upgrading from v3
Recurly.js v4 introduced the concept of Elements. These are a more secure method of capturing customer card data, ensuring that their payment information is never exposed to your payment form. This is a huge benefit for security and reduced PCI compliance exposure.
First, you will need to update your payment form. The credit card fields `number`, `month`, `year`, and `cvv` will need to be removed and replaced with a container element in the form ``. The id is entirely optional, and is simply added for ease of reference. We recommend using the card field since it incorporates validation and UX improvements, but it is also possible to use separate fields for the number, month, year, and cvv. This is explained more completely in the [Getting Started](https://docs.recurly.com/v1.2/docs/getting-started#/) section.
Your `recurly.token` call may also need to be updated. It is now necessary to pass a reference to your `Elements` instance and the checkout `