react-plaid-link

react-plaid-link is Plaid’s official React binding for Plaid Link, the hosted UI flow users go through to connect a bank account to your app. Rather than manipulating Plaid’s vanilla Link.js script directly, developers get a usePlaidLink hook (and a prebuilt PlaidLink button component for legacy class-component codebases) that manages script loading, instance creation/teardown, and the success/exit/event callback lifecycle for them.

The library also ships a PlaidEmbeddedLink component for inline (non-popup) Link experiences, first-class support for OAuth redirect flows and Content Security Policy nonces, and typed definitions for every Link callback payload (accounts, institution metadata, error codes). It targets the full spread of React versions still in active use, from 16.8 through 19, which the maintainers verify via a dedicated compatibility matrix in CI.

What You Get

• A usePlaidLink hook returning open, ready, submit, exit, and error state, with automatic Plaid instance creation and teardown as the link token or product list changes
• A prebuilt PlaidLink button component for integrating without hooks, useful in legacy class-component code
• A PlaidEmbeddedLink component for rendering Link inline in the page rather than as a popup overlay
• Automatic, deduplicated loading of the Plaid Link script, shared across multiple hook instances on the same page
• Built-in support for OAuth redirect continuation (receivedRedirectUri) and CSP nonce injection for nonce-based Content Security Policies
• Full TypeScript definitions for every Link configuration option and callback metadata shape (accounts, institution, errors, events)

Common Use Cases

• Adding a ‘Connect a bank account’ button that opens Plaid Link and forwards the resulting public_token to a backend for exchange
• Handling Plaid’s OAuth redirect flow, where Link must reopen automatically after the user returns from their bank’s site
• Embedding Link directly into a page layout (rather than as a popup) using PlaidEmbeddedLink for identity verification or Layer flows
• Recovering from an INVALID_LINK_TOKEN exit event by fetching a fresh link_token and re-initializing the hook
• Supporting legacy React class components that can’t use hooks via the PlaidLink wrapper component

Under The Hood

Architecture The library is organized around a small factory pattern: factory.ts’s createPlaid wraps the raw window.Plaid.create handler in an internal state object that tracks whether Link is currently open and exposes clean open/submit/exit/destroy methods, translating the legacy publicKey option to Plaid’s key field along the way. usePlaidLink.ts is the primary consumer — it loads the Plaid Link script via a forked useScript hook, then creates or recreates a Plaid factory instance whenever the token, publicKey, or product list changes, destroying the previous instance first to avoid leaked iframes. PlaidLink.tsx and PlaidEmbeddedLink.tsx are thin presentational wrappers: the former is a styled button driven entirely by the hook, while the latter bypasses the hook and calls window.Plaid.createEmbedded directly against a ref’d container div, since embedded Link manages its own handler internally. A change to the factory’s open/exit state machine would ripple into both the hook and, transitively, the PlaidLink button.

Tech Stack Written in strict-mode TypeScript targeting esnext, transpiled via Babel and bundled with Rollup into CommonJS, ESM, and UMD outputs (the UMD build inlines PropTypes via babel-plugin-typescript-to-proptypes for non-TypeScript consumers). React is a peer dependency spanning 16.8 through 19, with prop-types as the only runtime dependency. The project uses Yarn 1 with Corepack, ESLint (Airbnb config plus Prettier), and Husky to lint on pre-push.

Code Quality The hook, the embedded component, and the forked script-loading utility each have dedicated Jest + Testing Library test suites (roughly 700 lines combined) covering script-loading edge cases, instance recreation on token change, and exit/destroy cleanup. CI (GitHub Actions) runs a build/verify job plus a separate react-compatibility matrix job that reinstalls each supported React version and reruns typecheck and tests against it, which is a notably rigorous approach to peer-dependency compatibility for a library this size.

API Design The public surface is deliberately narrow and dual-mode: a single hook for modern function components, plus a drop-in button component for legacy call sites, both driven by the same underlying factory so behavior stays consistent between them. Configuration is a flat options object mirroring Plaid’s own Link API field-for-field, which keeps the learning curve low for anyone who has already read Plaid’s Link documentation, at the cost of inheriting some of Plaid’s own naming and deprecated-field baggage (e.g. the legacy publicKey path).