React SDK - picket-react

The Picket React SDK, picket-react, is a JavaScript library for integrating Picket into React apps. It gives access to a Picket context provider and custom hook for securing your app.

Installation

npm install --save "@picketapi/picket-react"

Usage - Quick Start

The PicketProvider creates a Picket context, which makes user authentication information available throughout your app! It takes a publishable API key as a prop.

import { PicketProvider } from "@picketapi/picket-react"

function MyApp({ children }) {
  return (
    <PicketProvider apiKey="YOUR_PUBLISHABLE_KEY_HERE">
      {children}
    </PicketProvider>
  );
}

We’ve placed a placeholder publishable API key in this example. Replace it with your actual publishable API key.

After instantiating the PicketProvider, you can use the usePicket hook to get user authentication information within your app. Below is an example of a component that renders different information based on the user's authentication state.

import { usePicket } from "@picketapi/picket-react"

const MySecurePage = () => {
  const { 
          isAuthenticating, 
          isAuthenticated, 
          authState, 
          logout,
          login
          } = usePicket();
  
  // user is logging in
  if (isAuthenticating) return "Loading";

  // user is not logged in
  if (!isAuthenticated) {
      return (
        <div>
            <p>You are not logged in!</p>
            <button onClick={() => login()}>Login with Wallet</button>
        </div>
      )
  }

  // user is logged in 🎉
  const { user } = authState;
  const { walletAddress } = user;
  
  return (
    <div>
       <p>You are logged in as {walletAddress} </p>
       <button onClick={() => logout()}>Logout</button>
    </div>
  )
}

The usePicket hook provides your components information about the user's authentication state. You can use it to require authentication on specific routes, get user information, or get the login and logout functions.

PicketProvider

PicketProvider is a React context provider. It makes the Picket context available throughout your app and easily accessible via the usePicket hook.

It's typical to wrap the outer-most component with the PicketProvider to make a user's authentication and authorization state globally available to all child components.

import { PicketProvider } from "@picketapi/picket-react"

function MyApp({ children }) {
  return (
    <PicketProvider apiKey="YOUR_PUBLISHABLE_KEY_HERE">
      {children}
    </PicketProvider>
  );
}

Themes

The Picket Login Modal supports several themes. By default the login modal will use the light theme. However, you can set it to a different theme to best fit into your overall web experience.

You can set the theme by passing a prop to the PicketProvider

import { PicketProvider } from "@picketapi/picket-react"

function MyApp({ children }) {
  return (
    {/* sets theme to dark */}
    <PicketProvider apiKey="YOUR_PUBLISHABLE_KEY_HERE" theme="dark">
      {children}
    </PicketProvider>
  );
}

Supported themes can be found here.

usePicket

usePicket is a wrapper around the useContext React hook that makes all Picket-related authentication information accessible.

import { usePicket } from "@picketapi/picket-react"

const MySecureComponent = () => {
  const { 
          isAuthenticating, 
          isAuthenticated,
          authState, 
          logout,
          login
          } = usePicket();
  // do something with the user's authentication state
  // redirect not logged in
  // make API requests with access token
  // display wallet address
  // etc
  return isAuthenticated ? "you've logged in 😎" : "you need to login 🚨";
}

Name	Type	Description
isAuthenticating	bool	True if the login process has started and hasn't finished or Picket is validating the cached access token on initialization
isAuthenticated	bool	True if the user has recently logged in and there is a cached, valid access token
isAuthorized	function	Given authorization requirements, check if the current user is authorized. This is equivalent to isCurrentUserAuthorized in picket-js
isAlreadyAuthorized	function	Check if the current user has already been authorized. This is synchronous, local-only check. I is useful for showing different states for UI elements.
authState	AuthState | null	The auth state contains the data from the last successful login. null if the user is not authenticated
error	Error	The latest error, if any, when authenticating a user. error is helpful for knowing when to display error messages to users.
login	function	The picket-js login function
logout	function	The picket-js logout function
loginWithRedirect	function	The picket-js loginWithRedirect function
loginWithPopup	function	The picket-js loginWithPopup function

PicketRainbowAuthProvider

PicketRainbowAuthProvider allows you to use Picket for authentication and authorization with the RainbowKit modal.

Interested in learning more? Go to the Picket Authentication with RainbowKit integration page.

import { PicketRainbowAuthProvider } from "@picketapi/picket-react";

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <WagmiConfig client={wagmiClient}>
      {/* 
        1. ORDER MATTERS! PicketRainbowAuthProvider must be nested 
           between WagmiConfig and RainbowKitProvider
        2. Replace YOUR_PUBLISHABLE_KEY_HERE with your project's publishable key
      */}
      <PicketRainbowAuthProvider apiKey="YOUR_PUBLISHABLE_KEY_HERE">
        <RainbowKitProvider chains={chains}>
          <Component {...pageProps} />
        </RainbowKitProvider>
      </PicketRainbowAuthProvider>
    </WagmiConfig>
  );
}