React Elements SDK

React Elements SDK

elements

See it in GitHub

PublicSquare React Elements is a package designed to allow you to easily integrate PublicSquare JS SDK and Elements features in your React solution.

This section provides specific documentation for how to initialize a PublicSquare instance using Hooks, pass it to your component tree with Context and then declare Elements Components in your code use the underlying Element.

Creating, mounting, updating and unmounting Elements is as simple as declaring them as a typical React Components and passing props.

Before You Begin

This SDK requires the use of a Publishable API Key. Go to your Developers section and click Reveal for your Publishable Key and copy the value.

Installation

npm

npm install --save @publicsquare/elements-react

yarn

yarn add @publicsquare/elements-react

You don't need to install @publicsquare/elements-js separately when using our React package. Types are available via the @publicsquare/elements-react/types module.

Versions

@publicsquare/elements-react wraps @publicsquare/elements-js and is versioned in lockstep — each release of the React SDK pins the exact same version of the underlying JavaScript SDK, so the same production sandbox testing requirements apply.

Recommended version: 1.16.1.

If you're testing against a production sandbox (test-mode transactions using a production account), you need to be on 1.16.1 specifically — older versions will not work for this scenario.

1.16.1 is the current fix, not the start of a version range. There is no confirmed compatibility beyond 1.16.1 yet — this section will be updated as new versions are released, rather than assumed to extend automatically.

Version compatibility

Version	Test mode against staging	Test mode against production
< 1.16.0	Works	Not supported
1.16.0	Works	Works, but requires an additional configuration parameter to route correctly. Not recommended — upgrade to 1.16.1 instead.
1.16.1	Works	Works automatically, no extra configuration needed

Starting in 1.16.1, Elements automatically detects your environment by inspecting your Publishable Key and routes accordingly. No additional setup is required beyond using the correct key for your environment.

The CDN distribution described in the JavaScript Elements SDK docs applies only to @publicsquare/elements-js. There is no separate CDN build for @publicsquare/elements-react — install it via npm or yarn.

If using npm

Check your installed version:

npm list @publicsquare/elements-react

Upgrade to the confirmed fix version:

npm install --save @publicsquare/elements-react@1.16.1

Install the specific version above rather than @latest — 1.16.1 is the confirmed fix, not necessarily the newest published version. Always confirm the actual latest version before installing it.

See the GitHub Releases page for the full version history and changelog.

Initialization

PublicSquareProvider

This Context Provider shares an instance of the React Elements SDK to your component tree, making it available for Elements Components or other custom components.

import {
  PublicSquareProvider,
  TextElement,
  usePublicSquare,
} from "@publicsquare/elements-react";

export default function App() {
  return (
    <PublicSquareProvider apiKey={apiKey}>
      <MyComponent />
    </PublicSquareProvider>
  );
};

const MyComponent = () => {
  // calling this hook with no attributes grabs the instance from Context
  const { publicsquare } = usePublicSquare();

  if (publicsquare) {
    // able to call PublicSquare methods
  }

  return <CardElement id="myInput" />; // Element will also grab it from the Context
};

Using Refs

Refs are a way to access DOM nodes or React component instances.

refs are utilized to store or receive (in the case of a callback ref) the underlying PublicSquare Elements instance, to tokenize their value or call one of its methods.

import { useRef } from "react";
import {
  PublicSquareProvider,
  CardElement,
  usePublicSquare,
} from "@publicsquare/elements-react";

export default function App() {
  return (
    <PublicSquareProvider apiKey={apiKey}>
      <MyComponent />
    </PublicSquareProvider>
  );
};

const MyForm = () => {
  const { publicsquare } = usePublicSquare();
  const cardRef = useRef(null);

  const submit = async () => {
    const card = cardRef.current;

    try {
      const tokens = await publicsquare.cards.create({
        cardholder_name: 'John Smith',
        card,
      });
    } catch (error) {
      // check error details
    }
  };

  return (
    <>
      <CardElement
        id="card"
        ref={cardRef}
      />
      <div>
        <button type="submit" onClick={submit} disabled={!publicsquare}>
          Submit
        </button>
      </div>
    </>
  );
};

When using Typescript, you can type-cast the element ref to safely to a specific Elements Component type.

import { useRef } from "react";
import type { CardExpirationDateElement } from "@publicsquare/elements-react/types";

const expirationDateRef = useRef(null);

expirationDateRef.current.month(); // Error TS2551: property doesn't exist

const expirationDateRef = useRef<CardExpirationDateElement>(null);

expirationDateRef.current.month(); // no error