react-plaid-link

library4.1.1jsnpmunverified

react-plaid-link is a React component and hook library designed for integrating Plaid Link into React applications. As of version 4.1.1, it provides a modern, idiomatic React interface, primarily through the `usePlaidLink` hook, to manage the Plaid Link user experience. The library abstracts away the complexities of embedding and interacting with the Plaid Link JavaScript SDK, handling initialization, callbacks, and lifecycle events. It supports a wide range of React versions, from 16.8 up to 19, demonstrating active maintenance and compatibility with the latest React ecosystems. While the README does not specify a strict release cadence, the version history suggests regular updates to maintain compatibility and incorporate new Plaid Link features. Its primary differentiator is simplifying Plaid Link integration for React developers, offering explicit callback handlers for success, exit, and events, and clear mechanisms for handling OAuth flows.

payments

npm install react-plaid-link

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-PLAID-LINK

react-plaid-link

paymentsjavascriptv4.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

usePlaidLink

✓ import { usePlaidLink } from 'react-plaid-link';

✗ const { usePlaidLink } = require('react-plaid-link');

This is the primary hook for integrating Plaid Link. It's a named export, not a default export. CommonJS `require` is generally not supported in modern React setups.

PlaidLinkOnSuccessMetadata

✓ import type { PlaidLinkOnSuccessMetadata } from 'react-plaid-link';

✗ import { PlaidLinkOnSuccessMetadata } from 'react-plaid-link';

For importing types, use `import type` for clarity and better tree-shaking/bundler optimizations, especially if the type is not also a runtime value.

PlaidLinkOnExitMetadata

✓ import type { PlaidLinkOnExitMetadata, PlaidLinkError } from 'react-plaid-link';

✗ import { PlaidLinkOnExitMetadata, PlaidLinkError } from 'react-plaid-link';

Similar to other types, prefer `import type` when only using the imported symbols for type annotations in TypeScript.

Demonstrates how to integrate Plaid Link using the `usePlaidLink` hook, fetching a `link_token` (simulated), and handling success, exit, and loading callbacks. It correctly disables the button until Link is ready.

import React, { useEffect, useState } from 'react'; import { usePlaidLink, PlaidLinkOnSuccessMetadata, PlaidLinkOnExitMetadata, PlaidLinkError } from 'react-plaid-link'; const MyPlaidLinkComponent: React.FC = () => { // In a real application, the link_token is generated server-side. // For this example, replace '<YOUR_GENERATED_LINK_TOKEN>' with a valid token // fetched from your backend. If you don't have one, Plaid offers a quickstart // for generating development tokens. const [linkToken, setLinkToken] = useState<string | null>(null); useEffect(() => { // Simulate fetching link_token from your backend const fetchLinkToken = async () => { try { // Example: const response = await fetch('/api/create-link-token'); // const data = await response.json(); // setLinkToken(data.link_token); // Using a placeholder for demonstration purposes setLinkToken('link-development-YOURPLAIDCLIENTID'); // Replace with a real token! } catch (error) { console.error('Error fetching link token:', error); } }; fetchLinkToken(); }, []); const { open, ready, error } = usePlaidLink({ token: linkToken, onSuccess: (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => { // Send the public_token to your server to exchange for an access_token console.log('Plaid Link successful! Public Token:', public_token, 'Metadata:', metadata); alert(`Public token received: ${public_token}`); // Typically, you'd send this to your backend: // fetch('/api/exchange_public_token', { // method: 'POST', // headers: { 'Content-Type': 'application/json' }, // body: JSON.stringify({ public_token, metadata }), // }); }, onExit: (error: PlaidLinkError | null, metadata: PlaidLinkOnExitMetadata) => { console.error('Plaid Link exited:', error, 'Metadata:', metadata); }, onEvent: (eventName: string, metadata: any) => { console.log('Plaid Link event:', eventName, metadata); }, onLoad: () => { console.log('Plaid Link loaded.'); } }); return ( <div> <h1>Connect to Plaid</h1> <button onClick={() => open()} disabled={!ready || !linkToken}> Connect Bank Account </button> {error && <p style={{ color: 'red' }}>Error during Plaid Link initialization: {error.message}</p>} {!linkToken && <p>Loading Plaid Link token...</p>} {!ready && linkToken && <p>Plaid Link is loading and not yet ready to open.</p>} </div> ); }; export default MyPlaidLinkComponent;

Debug

Known issues

breakingMajor version updates (e.g., from v3 to v4) often introduce breaking changes, particularly in API signatures and the preferred integration approach (e.g., moving from class components to hooks). Existing implementations might require significant refactoring.

fix

Consult the official GitHub release notes and migration guides provided by Plaid for `react-plaid-link` when upgrading across major versions to understand specific changes and required updates.

affects: >=3.0.0

gotchaThe `link_token` is a critical security credential that MUST be generated securely on your server-side application using the Plaid API. It should never be generated client-side directly within your React application due to security risks and API limitations.

fix

Implement a secure backend endpoint (e.g., Node.js, Python, Ruby) to call the Plaid API's `/link/token/create` endpoint and return the generated `link_token` to your frontend. Your React app should then fetch this token before initializing `usePlaidLink`.

affects: >=1.0.0

gotchaWhen handling OAuth flows, Plaid Link often needs to be opened immediately upon page load (e.g., after a redirect) rather than waiting for a user interaction. Incorrect handling can lead to broken OAuth experiences.

fix

Utilize a `React.useEffect` hook to conditionally call `open()` when the `ready` flag from `usePlaidLink` becomes `true` and a `receivedRedirectUri` is present, as shown in the library's OAuth examples.

affects: >=1.0.0

gotchaEnsure your project's `react` and `react-dom` versions are compatible with the `react-plaid-link` peer dependencies (`^16.8.0 || ^17 || ^18 || ^19`). Incompatible peer dependencies can lead to runtime errors, hook issues, or build failures, even if the package installs successfully.

fix

Verify the `react` and `react-dom` versions in your `package.json` file. Update them to a compatible range if necessary and run `npm install` or `yarn install` to ensure correct resolution of peer dependencies.

affects: >=1.0.0

Errors

Common errors & fixes

Plaid Link exited: { error_code: 'INVALID_LINK_TOKEN', error_type: 'ITEM_ERROR', ... }

The `link_token` provided to the `usePlaidLink` hook is invalid, expired, or malformed, preventing Plaid Link from initializing correctly.

fix

Verify your backend is generating a valid, non-expired `link_token` using the Plaid API and that it's correctly passed to the `usePlaidLink` hook. Plaid Link tokens typically expire after 30 minutes, so fetch a fresh one for each new Link session.

Cannot read properties of undefined (reading 'open') OR open is not a function

You are attempting to call the `open()` function returned by `usePlaidLink` before the Plaid Link script has fully loaded and initialized, or `open` was not correctly destructured.

fix

Always check the `ready` boolean flag returned by `usePlaidLink` before calling `open()`. For example, `disabled={!ready}` on your button. Also, ensure `const { open, ready } = usePlaidLink(...)` correctly destructures the hook's return value.

Invariant Violation: Invalid hook call. Hooks can only be called inside of the body of a function component.

The `usePlaidLink` hook is being called outside of a functional React component or a custom hook, which violates React's Rules of Hooks.

fix

Ensure `usePlaidLink` is invoked directly within the top level of a functional React component or another custom hook, and not inside loops, conditions, or nested functions.

TypeError: Cannot destructure property 'open' of 'Object(...)' as it is null.

The `usePlaidLink` hook might be returning `null` or `undefined` in some edge cases (e.g., critical initialization failure, or if React context is misconfigured, though less common for this specific error).

fix

Check for errors during `usePlaidLink` initialization (e.g., `error` return value). Ensure your React environment is set up correctly and no other issues are preventing the hook from returning its expected object. This error is rare and often points to a deeper React environment problem.

Upgrade

Version history

4.1.1latest on npm

Audit

Dependencies

reactrequiredPeer dependency required for all React applications using this library.

react-domrequiredPeer dependency required for rendering React components to the DOM.

Agent activity

26 hits · last 30 days

node

Resources

githubhttps://github.com/plaid/react-plaid-link ↗

packagehttps://www.npmjs.com/package/react-plaid-link ↗

homepagehttps://plaid.com ↗