# react-plaid-link

> A React component for Plaid Link

Latest version **5.0.0** (published 2026-07-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-plaid-link
pnpm add react-plaid-link
yarn add react-plaid-link
bun add react-plaid-link
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.0.0 |
| Published | 2026-07-24 |
| First published | 2016-04-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 124.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 289 |
| Maintainers | clayallsopp, plaid-admin, andchen, phoenixy1, myauplaid, ktse4, plaid-devx |
| Keywords | react, react-component, plaid |

## Links

- npm: https://www.npmjs.com/package/react-plaid-link
- Repository: https://github.com/plaid/react-plaid-link
- Issues: https://github.com/plaid/react-plaid-link/issues
- npm.io page: https://npm.io/package/react-plaid-link

## Dependencies (1)

- [prop-types](https://npm.io/package/prop-types.md) ^15.7.2

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 5.0.0 (latest) — 2026-07-24
- 3.6.0-beta.1 (beta) — 2024-08-29
- 4.2.0 — 2026-07-23
- 4.1.1 — 2025-08-06
- 4.0.1 — 2025-04-15
- 4.0.0 — 2025-04-10
- 3.6.1 — 2024-10-30
- 3.6.0 — 2024-09-05
- 3.6.0-beta.0 — 2024-08-29
- 3.5.2 — 2024-06-13
- 3.5.1 — 2023-10-13
- 3.5.0 — 2023-10-13
- 3.4.1 — 2023-09-29
- 3.4.0 — 2023-02-22
- 3.4.0-beta.0 — 2022-11-08
- … 44 more at https://npm.io/package/react-plaid-link/versions

## README

# react-plaid-link [![npm version](https://badge.fury.io/js/react-plaid-link.svg)](https://www.npmjs.com/package/react-plaid-link)

[React](https://react.dev/) hooks and components for integrating
with [Plaid Link](https://plaid.com/docs/link/)

### Compatibility

React 16.8-19.x.x

### Install

With `npm`:

```
npm install --save react-plaid-link
```

With `yarn`:

```
yarn add react-plaid-link
```

## Documentation

Please refer to the [official Plaid Link docs](https://plaid.com/docs/link/)
for a more holistic understanding of Plaid Link.

## Examples

Head to the `react-plaid-link`
[storybook](https://plaid.github.io/react-plaid-link) to try out a live demo.

See the [examples folder](examples) for various complete source code examples.

## Using React hooks

This is the preferred approach for integrating with Plaid Link in React.

**Note:** `token` can be `null` initially and then set once you fetch or generate
a `link_token` asynchronously.

ℹ️ See full source code examples of using hooks:

- [examples/simple.tsx](examples/simple.tsx): minimal example of using hooks
- [examples/hooks.tsx](examples/hooks.tsx): example using hooks with all
  available callbacks
- [examples/oauth.tsx](examples/oauth.tsx): example handling OAuth with hooks
- [examples/layer.tsx](examples/layer.tsx): example implementing Plaid Layer

```tsx
import React from 'react';
import { usePlaidLink } from 'react-plaid-link';

// ...

const { open, ready } = usePlaidLink({
  token: '<GENERATED_LINK_TOKEN>',
  onSuccess: (public_token, metadata) => {
    // send public_token to server
  },
});

return (
  <button onClick={() => open()} disabled={!ready}>
    Connect a bank account
  </button>
);
```

### Available Link configuration options

ℹ️ See [src/types/index.ts][types] for exported types.

Please refer to the [official Plaid Link
docs](https://plaid.com/docs/link/web/) for a more holistic understanding of
the various Link options and the
[`link_token`](https://plaid.com/docs/api/link/#linktokencreate).

#### `usePlaidLink` arguments

| key                   | type                                                                                      |
| --------------------- | ----------------------------------------------------------------------------------------- |
| `token`               | `string \| null`                                                                          |
| `onSuccess`           | `(public_token: string \| null, metadata: PlaidLinkOnSuccessMetadata) => void`             |
| `onExit`              | `(error: null \| PlaidLinkError, metadata: PlaidLinkOnExitMetadata) => void`              |
| `onEvent`             | `(eventName: PlaidLinkStableEvent \| string, metadata: PlaidLinkOnEventMetadata) => void` |
| `onLoad`              | `() => void`                                                                              |
| `receivedRedirectUri` | `string \| undefined`                                                                     |
| `cspNonce`            | `string \| undefined`                                                                     |

`public_token` is `null` for flows such as Identity Verification that do not
create an Item.

#### Content Security Policy nonce

If your app uses a nonce-based Content Security Policy, generate a fresh nonce
per page response and pass it as `cspNonce`
on `usePlaidLink` or `PlaidEmbeddedLink`. Only mount these components once
`cspNonce` is known.

Allow that nonce in `script-src`, `style-src`, and `style-src-elem`. Link still
requires `style-src-attr 'unsafe-inline'` today. You will also need `frame-src` and `connect-src` as
[documented for Link Web](https://plaid.com/docs/link/web/#csp-directives); for
example:

```html
default-src https://cdn.plaid.com/;
script-src 'nonce-<PAGE_RESPONSE_NONCE>' https://cdn.plaid.com/link/v2/stable/link-initialize.js;
style-src 'nonce-<PAGE_RESPONSE_NONCE>';
style-src-elem 'nonce-<PAGE_RESPONSE_NONCE>';
style-src-attr 'unsafe-inline';
frame-src https://cdn.plaid.com/;
connect-src https://production.plaid.com/;
```

If you omit `cspNonce`, behavior is unchanged (including for embedded Link).

```tsx
const { open, ready } = usePlaidLink({
  token: '<GENERATED_LINK_TOKEN>',
  cspNonce: '<PER_RESPONSE_NONCE>',
  onSuccess: (public_token, metadata) => {
    // send public_token to server
  },
});
```

#### `usePlaidLink` return value

| key      | type                                                            |
|----------|-----------------------------------------------------------------|
| `open`   | `() => void`                                                    |
| `ready`  | `boolean`                                                       |
| `submit` | `(data: PlaidHandlerSubmissionData) => void`                    |
| `error`  | `ErrorEvent \| null`                                            |
| `exit`   | `(options?: { force?: boolean }, callback?: () => void) => void` |

For Layer, call `submit` with either `phone_number` or `date_of_birth`. See the
[complete Layer example](examples/layer.tsx) and
[Plaid Layer integration guide](https://plaid.com/docs/layer/add-to-app/).

### Handling an invalid Link token

If `onExit` receives an `INVALID_LINK_TOKEN` error, fetch a new Link token and
update the token in state. `usePlaidLink` destroys the old Link instance and
creates a new one whenever the token changes. See Plaid's guide to
[handling an invalid Link token](https://plaid.com/docs/link/handle-invalid-link-token/)
for more context.

```tsx
import React from 'react';
import { PlaidLinkError, usePlaidLink } from 'react-plaid-link';

const [token, setToken] = React.useState<string | null>(null);

const onExit = React.useCallback(async (error: PlaidLinkError | null) => {
  if (error?.error_code === 'INVALID_LINK_TOKEN') {
    setToken(null);
    const response = await fetch('/api/create_link_token', { method: 'POST' });
    const { link_token } = await response.json();
    setToken(link_token);
  }
}, []);

const { open, ready } = usePlaidLink({
  token,
  onExit,
  onSuccess: (public_token, metadata) => {
    // send public_token to server
  },
});
```

### OAuth / opening Link without a button click

Handling OAuth redirects requires opening Link without any user input (such as
clicking a button). This can also be useful if you simply want Link to open
immediately when your page or component renders.

ℹ️ See full source code example at [examples/oauth.tsx](examples/oauth.tsx)

```tsx
import React from 'react';
import { usePlaidLink } from 'react-plaid-link';

// ...

const { open, ready } = usePlaidLink(config);

// open Link immediately when ready
React.useEffect(() => {
  if (ready) {
    open();
  }
}, [ready, open]);

return <></>;
```

## Using the pre-built component instead of the usePlaidLink hook

If you cannot use React hooks for legacy reasons such as incompatibility with
class components, you can use the `PlaidLink` component.

ℹ️ See full source code example at [examples/component.tsx](examples/component.tsx)

```tsx
import React from 'react';
import { PlaidLink } from 'react-plaid-link';

const App extends React.Component {
  // ...
  render() {
    return (
      <PlaidLink
        token={this.state.token}
        onSuccess={this.onSuccess}
        // onEvent={...}
        // onExit={...}
      >
        Link your bank account
      </PlaidLink>
    );
  }
}
```

## TypeScript support

TypeScript definitions for `react-plaid-link` are built into the npm package.
If you have previously installed `@types/react-plaid-link` before this package
had types, please uninstall it in favor of built-in types.

[types]: https://github.com/plaid/react-plaid-link/blob/master/src/types/index.ts

---
_Source: https://npm.io/package/react-plaid-link · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._