{"id":11825,"library":"react-plaid-link","title":"React Plaid Link Integration","description":"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.","status":"active","version":"4.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/plaid/react-plaid-link","tags":["javascript","react","react-component","plaid","typescript"],"install":[{"cmd":"npm install react-plaid-link","lang":"bash","label":"npm"},{"cmd":"yarn add react-plaid-link","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-plaid-link","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for all React applications using this library.","package":"react","optional":false},{"reason":"Peer dependency required for rendering React components to the DOM.","package":"react-dom","optional":false}],"imports":[{"note":"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.","wrong":"const { usePlaidLink } = require('react-plaid-link');","symbol":"usePlaidLink","correct":"import { usePlaidLink } from 'react-plaid-link';"},{"note":"For importing types, use `import type` for clarity and better tree-shaking/bundler optimizations, especially if the type is not also a runtime value.","wrong":"import { PlaidLinkOnSuccessMetadata } from 'react-plaid-link';","symbol":"PlaidLinkOnSuccessMetadata","correct":"import type { PlaidLinkOnSuccessMetadata } from 'react-plaid-link';"},{"note":"Similar to other types, prefer `import type` when only using the imported symbols for type annotations in TypeScript.","wrong":"import { PlaidLinkOnExitMetadata, PlaidLinkError } from 'react-plaid-link';","symbol":"PlaidLinkOnExitMetadata","correct":"import type { PlaidLinkOnExitMetadata, PlaidLinkError } from 'react-plaid-link';"}],"quickstart":{"code":"import React, { useEffect, useState } from 'react';\nimport { usePlaidLink, PlaidLinkOnSuccessMetadata, PlaidLinkOnExitMetadata, PlaidLinkError } from 'react-plaid-link';\n\nconst MyPlaidLinkComponent: React.FC = () => {\n  // In a real application, the link_token is generated server-side.\n  // For this example, replace '<YOUR_GENERATED_LINK_TOKEN>' with a valid token\n  // fetched from your backend. If you don't have one, Plaid offers a quickstart\n  // for generating development tokens.\n  const [linkToken, setLinkToken] = useState<string | null>(null);\n\n  useEffect(() => {\n    // Simulate fetching link_token from your backend\n    const fetchLinkToken = async () => {\n      try {\n        // Example: const response = await fetch('/api/create-link-token');\n        // const data = await response.json();\n        // setLinkToken(data.link_token);\n        // Using a placeholder for demonstration purposes\n        setLinkToken('link-development-YOURPLAIDCLIENTID'); // Replace with a real token!\n      } catch (error) {\n        console.error('Error fetching link token:', error);\n      }\n    };\n    fetchLinkToken();\n  }, []);\n\n  const { open, ready, error } = usePlaidLink({\n    token: linkToken,\n    onSuccess: (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => {\n      // Send the public_token to your server to exchange for an access_token\n      console.log('Plaid Link successful! Public Token:', public_token, 'Metadata:', metadata);\n      alert(`Public token received: ${public_token}`);\n      // Typically, you'd send this to your backend:\n      // fetch('/api/exchange_public_token', {\n      //   method: 'POST',\n      //   headers: { 'Content-Type': 'application/json' },\n      //   body: JSON.stringify({ public_token, metadata }),\n      // });\n    },\n    onExit: (error: PlaidLinkError | null, metadata: PlaidLinkOnExitMetadata) => {\n      console.error('Plaid Link exited:', error, 'Metadata:', metadata);\n    },\n    onEvent: (eventName: string, metadata: any) => {\n      console.log('Plaid Link event:', eventName, metadata);\n    },\n    onLoad: () => {\n      console.log('Plaid Link loaded.');\n    }\n  });\n\n  return (\n    <div>\n      <h1>Connect to Plaid</h1>\n      <button onClick={() => open()} disabled={!ready || !linkToken}>\n        Connect Bank Account\n      </button>\n      {error && <p style={{ color: 'red' }}>Error during Plaid Link initialization: {error.message}</p>}\n      {!linkToken && <p>Loading Plaid Link token...</p>}\n      {!ready && linkToken && <p>Plaid Link is loading and not yet ready to open.</p>}\n    </div>\n  );\n};\n\nexport default MyPlaidLinkComponent;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Major 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Ensure 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `link_token` provided to the `usePlaidLink` hook is invalid, expired, or malformed, preventing Plaid Link from initializing correctly.","error":"Plaid Link exited: { error_code: 'INVALID_LINK_TOKEN', error_type: 'ITEM_ERROR', ... }"},{"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.","cause":"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.","error":"Cannot read properties of undefined (reading 'open') OR open is not a function"},{"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.","cause":"The `usePlaidLink` hook is being called outside of a functional React component or a custom hook, which violates React's Rules of Hooks.","error":"Invariant Violation: Invalid hook call. Hooks can only be called inside of the body of a function component."},{"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.","cause":"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).","error":"TypeError: Cannot destructure property 'open' of 'Object(...)' as it is null."}],"ecosystem":"npm"}