React components for Recurly.js
A great way to get started is to try the interactive demo in our documentation, and look through the demo source on GitHub.
Install this package with npm
npm install @recurly/react-recurly
Then, include recurly.js in your application via our CDN.
<script src="https://js.recurly.com/v4/recurly.js"></script>
<!-- optional: include recurly.css -->
<link rel="stylesheet" href="https://js.recurly.com/v4/recurly.css">
In this guide, we will cover the steps necessary to create a payment form that will submit your user's payment information to Recurly.
ℹ️ If you haven't yet, please review the Recurly.js documentation. This will give you a solid understanding of the total capabilities of the library before we begin implementing some of its features in React.
To start, we will use the <RecurlyProvider /> component to set our public key.
// app.js
import React from 'react';
import { RecurlyProvider } from '@recurly/react-recurly';
function App () {
return (
<RecurlyProvider publicKey="MY_PUBLIC_KEY" />
);
}
Now we can set up our payment form. For this, we will use Recurly.js Elements. First, we will use the <Elements /> component to group our Elements together. We'll also create a <MyPaymentForm />
component to contain our payment form.
// app.js
import React from 'react';
import { RecurlyProvider, Elements } from '@recurly/react-recurly';
import { MyPaymentForm } from './my-payment-form';
function App () {
return (
<RecurlyProvider publicKey="MY_PUBLIC_KEY">
<Elements>
<MyPaymentForm />
</Elements>
</RecurlyProvider>
);
}
Within our new <MyPaymentForm />
component, we'll add a <CardElement /> which will render a secure card element. We'll also add inputs for our users' name. To let react-recurly know that we want to use these fields, we'll use a data-recurly
attribute. To include additional properties, see this billing fields table.
// my-payment-form.js
import React from 'react';
import { CardElement } from '@recurly/react-recurly';
export function MyPaymentForm (props) {
return (
<form>
<input type="text" data-recurly="first_name" placeholder="First name" />
<input type="text" data-recurly="last_name" placeholder="Last name" />
<CardElement />
</form>
);
}
We are now ready to add the final step: getting a token. When our users submit our form, we want to send their payment information to Recurly, which will return a token. We'll then keep this token to use in the Recurly API.
To accomplish this, we will use the useRecurly hook. This hook returns a Recurly.js instance, on which we will call recurly.token. Since this function expects a <form>
, we will create a React ref to pass to it.
// my-payment-form.js
import React from 'react';
import { CardElement, useRecurly } from '@recurly/react-recurly';
export function MyPaymentForm (props) {
const formRef = React.useRef();
const recurly = useRecurly();
function handleSubmit (event) {
event.preventDefault();
recurly.token(formRef.current, (err, token) => {
if (err) {
// handle error
} else {
// save the token.id, and submit it to the Recurly API from your server
}
});
}
return (
<form onSubmit={handleSubmit} ref={formRef}>
<input type="text" data-recurly="first_name" placeholder="First name" />
<input type="text" data-recurly="last_name" placeholder="Last name" />
<CardElement />
</form>
);
}
With that, we have implemented the essential components of a payment form using react-recurly. The tokens generated above may be used on any billing_info
object in the Recurly API.
React-recurly also includes a useCheckoutPricing hook for generating a pricing preview before checking out.
import { useCheckoutPricing, RecurlyProvider } from '@recurly/react-recurly';
function PricingPreview () {
const initialPricingInput = {
subscriptions: [
{
plan: 'my-plan'
}
]
};
const [{ price, loading }, setCheckoutPricing] = useCheckoutPricing(initialPricingInput);
if (!loading) {
return <div>{price.now.subtotal}</div>
};
};
export default function MyApp () {
<RecurlyProvider>
<PricingPreview />
</RecurlyProvider>
};
For more details, see the useCheckoutPricing Documentation.
- Documentation & Reference
- Recurly.js Documentation
- Interactive Demo
- Code on GitHub
- Package on npm
- Recurly API Documentation
- Questions? GitHub issues and Recurly support are here for you.
MIT