Parallel Markets JavaScript React Components

This library provides a loading wrapper for the Parallel Markets JavaScript SDK with React components.
For a quick start, check out the example React app.
Installation
Use npm
to install the Parallel JS SDK module and this React library:
$> npm install --save @parallelmarkets/react @parallelmarkets/vanilla
ParallelProvider
The ParallelProvider
allows you to use our hooks and access the Parallel object in any nested component. Render a ParallelProvider at the root of your React app so that it is available everywhere you need it.
To use the ParallelProvider
, call loadParallel from @parallelmarkets/vanilla
with your configuration options.
The loadParallel
function asynchronously loads the parallel.js script and initializes a Parallel object. Pass the returned Promise to ParallelProvider
.
import { loadParallel } from '@parallelmarkets/vanilla'
import { ParallelProvider } from '@parallelmarkets/react'
const parallel = loadParallel({ client_id: '123', environment: 'demo', flow_type: 'overlay' })
const App = () => (
<ParallelProvider parallel={parallel}>
<YourRootComponent />
</ParallelProvider>
)
const app = document.getElementById('main')
const root = createRoot(app)
root.render(<App />)
[!NOTE]
To best leverage Parallel's fraud detection, include the call to loadParallel
across your app/site. This allows Parallel to detect suspicious behavior that may be indicative of fraud as users interact with your website.
With ParallelProvider
in place, you can use the useParallel
hook in any component to get access to a number of useful properties and functions:
parallel
: This provides access to the full JS SDKloginStatus
: The current login status of the user. This is the result of a call to getLoginStatus()
, which may be null initially until a call to the API finishes.getProfile()
: A function that returns a Promise
that will be resolved with profile information (from a call to the Profile API)login()
: A shortcut to parallel.login()
logout()
: A shortcut to parallel.logout()
error
: Any error that resulted from getting the current login status on load
For instance:
Initiating a Parallel Flow
This is a more complete example, showing use of the useParallel
hook in a child component. Additionally, this example shows use of the PassportButton
component, that, when clicked, initiates a Parallel flow. You can simply call parallel.login()
as an alternative to showing the PassportButton
component.
import { loadParallel } from '@parallelmarkets/vanilla'
import { ParallelProvider, useParallel, PassportButton } from '@parallelmarkets/react'
const ParallelProfile = () => {
const { parallel, loginStatus } = useParallel()
if (!loginStatus) return null
return (
<>
<h1>Status: {loginStatus.status}</h2>
{/* Only show the login button if the user hasn't logged in yet */}
{loginStatus.status !== 'connected' ? (
<PassportButton />
) : (
<button onClick={parallel.logout}>Log Out</button>
)}
</>
)
}
const parallel = loadParallel({ client_id: '123', environment: 'demo', flow_type: 'overlay' })
const App = () => (
<ParallelProvider parallel={parallel}>
<ParallelProfile />
</ParallelProvider>
)
const root = createRoot(document.getElementById('main'))
root.render(<App />)
Getting the Parallel ID
The result of any successful authentication event will include an authResponse
field that indicates the status of the handoff. Once the status is connected
, you can call the getProfile()
function to get the Parallel ID for the user or business that completed the flow (along with other profile information). The ID can then be saved to your backend so your servers can make ongoing calls to get/update information for the user/business.
Here's an example of a few lines you can add to the example above if you want to send the profile information (including Parallel ID) to your backend.
const ParallelIDSaver = () => {
const { loginStatus, getProfile } = useParallel()
useEffect(() => {
if (loginStatus?.status !== 'connected') return
getProfile().then((profile) => {
const body = JSON.stringify({ profile, internalId: getInvestorId() })
fetch('/save-parallel-id', { method: 'POST', body })
})
}, [])
if (loginStatus?.status !== 'connected') return null
return <p>Thanks for providing your information!</p>
}
Embed Flow Type
While the "overlay" and "redirect" flow_type
options will work fine with React, the "embed" option will not. React recreates elements on render/re-render, causing any children iframe elements to be recreated, which results in reloading the URL in the src
attribute. This causes a reload of the Parallel experience within the iframe, which is not an ideal experience for users.
This issue on React’s Github has more info about the effect. Any movement of the iframe
element in the DOM (including recreating, as React does) will produce a re-fetching of the src
URL of the iframe
, resulting in a re-render of the Parallel experience.
We strongly recommend using the "overlay" flow_type
if you're using React.