README.mdx

react-recurly ·

React components for Recurly.js

Documentation

Documentation & Reference

Recurly.js Documentation

Examples

Interactive Demo

A great way to get started is to try the interactive demo in our documentation, and look through the demo source on GitHub.

Installation

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">

Implementation Guide

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.

Additional Usage

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.

Additional resources

• 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.

Licence

MIT