Skip to content

Using the Privy React SDK

At a high-level, there are two major integration surfaces between your app and Privy:

  • the PrivyProvider: a React component that loads the SDK and manages state
  • the usePrivy: a React hook that returns the SDK's key methods and state variables

Both can be imported directly from the SDK, like so:

tsx
import {PrivyProvider, usePrivy} from '@privy-io/react-auth';

The PrivyProvider Component

The PrivyProvider is a React component that loads the Privy SDK in your app.

Concretely, the component renders a React Context that manages your app's interactions with the Privy API and iframe and stores state about the current user and their wallet(s).

This component must wrap any component that will use Privy in your app. It is generally recommended to render this component as close to the root of your application as possible, to ensure your app's components and pages have sufficient access to the SDK.

The PrivyProvider also accepts a config property that can be used to customize Privy within your app, including its appearance, login methods, wallet configurations, and more! Read our configuration guide here.

The usePrivy Hook

Once you've set up the PrivyProvider component, you can then use Privy throughout your app via the usePrivy React hook.

usePrivy returns a set of methods and variables for authenticating and identifying your users, getting their auth status, creating embedded wallets for them, and more. A full list of methods and variables returned by the hook is available here.

Due to the nature of React hooks, there are certain rules for where usePrivy can be invoked:

  • The hook must be called from within a React component. The hook will throw an error if invoked outside of the scope of a component, as this is forbidden by React.
  • The component calling the hook must be wrapped by the PrivyProvider. Otherwise, the hook cannot access Privy's React Context, and will throw an error.

Please note that the Privy React SDK exports other hooks as well, including useWallets, useLogin, etc. You should use these hooks as necessary, but the primary integration point between your components and Privy is likely to be the usePrivy hook.