{"id":18369875,"url":"https://github.com/cawfree/react-native-use-plaid","last_synced_at":"2025-07-08T01:38:27.327Z","repository":{"id":65496498,"uuid":"592539985","full_name":"cawfree/react-native-use-plaid","owner":"cawfree","description":"⚛️ 💸 Simple hooks for Plaid open banking on React Native.","archived":false,"fork":false,"pushed_at":"2023-01-24T02:12:51.000Z","size":244,"stargazers_count":21,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-22T04:31:52.018Z","etag":null,"topics":["banking","fiat","link","open","plaid","react-native","sdk"],"latest_commit_sha":null,"homepage":"https://twitter.com/cawfree","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cawfree.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2023-01-24T00:02:35.000Z","updated_at":"2024-08-20T15:08:17.000Z","dependencies_parsed_at":"2023-02-13T11:30:43.518Z","dependency_job_id":null,"html_url":"https://github.com/cawfree/react-native-use-plaid","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawfree%2Freact-native-use-plaid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawfree%2Freact-native-use-plaid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawfree%2Freact-native-use-plaid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawfree%2Freact-native-use-plaid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cawfree","download_url":"https://codeload.github.com/cawfree/react-native-use-plaid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247531359,"owners_count":20953937,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["banking","fiat","link","open","plaid","react-native","sdk"],"created_at":"2024-11-05T23:32:51.801Z","updated_at":"2025-04-06T18:32:36.247Z","avatar_url":"https://github.com/cawfree.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [`react-native-use-plaid`](https://npmjs.com/package/react-native-use-plaid)\n⚛️ 💸 Simple hooks for [__Plaid__](https://plaid.com/) open banking on [__React Native__](https://reactnative.dev), which enables you to very quickly integrate with a user's bank account via a user-friendly onboarding process. What's contained here is the raw logic; you can customize the generic hooks arbitrarily for your own applications, navigation state and user journeys.\n\n## 🚀 Getting Started\n\nUsing [__Yarn__](https://yarnpkg.com/):\n\n```shell\nyarn add react-native-use-plaid react-native-webview\n```\nThis project depends on the [`react-native-webview`](https://github.com/react-native-webview/react-native-webview) Native Module.\n\n\u003e For vanilla React Native projects, you can install this as usual with `yarn add react-native-webview`. For [__Expo__](https://expo.dev/), you can use `npx expo install react-native-webview`.\n\n## ✍️ Usage\n\nThis package manages user bank authentication using [__Plaid Link__](https://plaid.com/docs/link/), which is used to orchestrate the authentication and  permissions process necessary to interact with a user's bank account, to do things like [__view their transaction history__](https://plaid.com/products/transactions/) or [__request a payment__](https://plaid.com/en-gb/use-cases/payments/).\n\nWe provide the appropriate life cycle hooks to easily initiate, persist, consume and relinquish connections to user bank accounts. Additionally, all user-facing onboarding has been expressed using Plaid's [`WebView`](https://github.com/react-native-webview/react-native-webview)-optimized onboarding process, making the integration process as straight-forward as possible.\n\n### 1. Configuring the `\u003cPlaidProvider /\u003e` 🔧\n\nFirst you'll need to wrap your application in a `PlaidProvider`, which manages global application state for all login processes:\n\n```typescript\nimport * as React from 'react';\nimport {PlaidProvider} from 'react-native-use-plaid';\n\nimport {MyNativeApp} from './src';\n\nexport default function App(): JSX.Element {\n  return (\n    \u003cPlaidProvider\n      redirectUri=\"https://cdn.plaid.com/link/v2/stable/link.html\" /* example */\n      basePath=\"sandbox\"\n      clientName=\"cawfree's kitchen\"\n      redirectUri=\"\u003cyour-redirect-uri\u003e\"\n      clientId=\"\u003cyour-client-id\u003e\"\n      clientSecret=\"\u003cyour-client-secret\u003e\"\u003e\n      \u003cMyNativeApp /\u003e\n    \u003c/PlaidProvider\u003e\n  );\n}\n```\n\nThis part is pretty straight forward; though you'll need to head over to the [__Plaid Developer Portal__](https://dashboard.plaid.com/signup) and create some API keys for your application.\n\nFor each application instance you register on Plaid, you're going to be given three different API keys for three different environments; `sandbox`, `development` and `production`. You'll see in the example above, we've configured our `PlaidProvider`'s `basePath` to work using `sandbox` credentials.\n\n\u003e ⚠️ You __must__ configure a `redirectUri` for your project from your project settings in Plaid, which is configured under [__the API tab__](https://dashboard.plaid.com/team/api) in your [__Team Settings__](https://dashboard.plaid.com/team).\n\n### 2. Connecting to accounts 👛\n\nOnce your application is wrapped in a `PlaidProvider`, you're free to start connecting with Plaid from any child component in your application.\n\nTo manage a connection, we call the `usePlaidLinkState` hook:\n\n```typescript\nimport {usePlaidLinkState} from 'react-native-use-plaid';\n\nconst client_user_id = '$myApplicationSpecificUserId';\n\nconst [state] = usePlaidLinkState({client_user_id});\n```\n\nThe returned `state` will delcare how far along in the connection process your user currently is.\n\n\u003e In Plaid, we identify users using the `client_user_id` field; this is a __unique__ identifier for an individual user native to your application stack.\n\nTo check if a `client_user_id`'s account is connected, you can use:\n\n```typescript\nimport {PlaidLinkStage} from 'react-native-use-plaid';\n\nconst {stage} = state;\n\nconst isConnected = stage === PlaidLinkStage.SUCCESS;\n```\n\nWhen a user is connected, their `state` will contain their [__Plaid Access Token__]():\n\n```typescript\nimport {PlaidLinkSuccessState} from 'react-native-use-plaid';\n\nconst {access_token} = state as PlaidLinkSuccessState;\n```\n\nThe `access_token` can be used to perform operations on a user account, for example, listing their transactions using the `client` instance returned by a call to `usePlaidLinkState`:\n\n```typescript\nimport {PlaidLinkStage, usePlaidLinkState} from 'react-native-use-plaid';\n\nconst [state, {client}] = usePlaidLinkState({client_user_id});\n\nconst {stage} = state;\n\nif (stage !== PlaidLinkStage.SUCCESS) return;\n\nconst {data} = await client.transactionsGet({\n  access_token: state.access_token,\n  start_date: '2018-01-01',\n  end_date: '2018-02-01',\n});\n```\n\n\u003e __Note:__ If we've checked that `stage === PlaidLinkStage.SUCCESS`, it is not necessary to cast the `state` as `PlaidLinkSuccessState` since this type will be automatically inferred.\n\nFinally, we need to see how to actually connect to a user. This is also done using the `usePlaidLinkState` hook, where we can call the `connect` function:\n\n```typescript\nimport {CountryCode, Products} from 'plaid';\n\nconst [, {connect, disconnect}] = usePlaidLinkState({\n  client_user_id,\n});\n\nawait connect({\n  country_codes: [CountryCode.Gb],\n  language: 'en',\n  products: [Products.Auth, Products.Transactions],\n});\n```\n\nWhen you call `connect`, `react-native-use-plaid` will manage the entire authentication process based on the given parameters end-to-end.\n\nThere is only a single obligation you have as the implementor: you need to find somewhere to render a `PlaidProviderLinkWebView`:\n\n\n```typescript\nimport {PlaidProviderLinkWebView} from 'react-native-use-plaid';\n\nreturn (\n  \u003cPlaidProviderLinkWebView\n    client_user_id=\"$myApplicationSpecificUserId\"\n  /\u003e\n);\n```\n\nThe `PlaidProviderLinkWebView` is the user-facing component of [__Plaid Link__](https://plaid.com/docs/link/).\n\nAll you need to do is present it; you could mount it in a [`\u003cModal visible /\u003e`](https://reactnative.dev/docs/modal), navigate to a dedicated screen using [`react-navigation`](https://reactnavigation.org/), you can use _any mechanism you desire_ to present this content to the user; what's important is you do render it!\n\nWithout the `PlaidProviderLinkWebView` visible to the user, they will be unable to complete the authentication process. Please check the [__example__](./example) for a simple demonstration of this concept.\n\n### 3. Persistence 💾\n\nAlthough the link process is relatively quick and simple for a user, it's something we should avoid doing too often since this inconveniences the user.\n\nIn the `PlaidProvider`, you can specify three additional properties to help you resume authentication state:\n\n```typescript\nimport * as React from 'react';\nimport {PlaidProvider} from 'react-native-use-plaid';\n\nexport default function App(): JSX.Element {\n  return (\n    \u003cPlaidProvider\n      // On launch, we can synchronously resume user sessions\n      // for individual users if we pass an access_token. Here\n      // we can track the authentication state of multiple users.\n      initialAccessTokens={React.useMemo(() =\u003e ({\n        '$myApplicationSpecificUserId': 'someAccessTokenFromPreviousSession',\n      }), [])}\n      // When a user begins a new session, onConnect is called providing\n      // the client_user_id and their access_token.\n      onConnect={React.useCallback(({client_user_id, access_token}) =\u003e {\n        console.log(`${client_user_id}'s access_token is \"${access_token}\"!`);\n      }, [])}\n      // When a user disconnects, `onDisconnect` is called.\n      onDisconnect={React.useCallback(({client_user_id}) =\u003e {\n        console.log(`${client_user_id} has disconnected.`);\n      }, [])}\n    /\u003e\n  );\n}\n````\n\nIn combination with a client persistence library such as [`react-native-async-storage`](https://github.com/react-native-async-storage/async-storage) or [`react-native-mmkv`](https://github.com/mrousavy/react-native-mmkv), user session state can be stored between launches of your application.\n\n## ✌️ License\n[__MIT__](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcawfree%2Freact-native-use-plaid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcawfree%2Freact-native-use-plaid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcawfree%2Freact-native-use-plaid/lists"}