# React SDK - picket-react

### Installation

```shell
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.

```typescript
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](https://picketapi.com/dashboard).&#x20;

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.

```typescript
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](https://reactjs.org/docs/context.html#api). It makes the Picket context available throughout your app and easily accessible via the [usePicket hook](#usepicket).&#x20;

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.

```typescript
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`

```tsx
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](https://docs.picketapi.com/picket-docs/reference/concepts/modal-themes).

### usePicket

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

```typescript
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](https://docs.picketapi.com/picket-docs/reference/javascript-library-picket-js#iscurrentuserauthorized) |
| `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* | <p>The auth state contains the data from the last successful login.</p><p></p><p>null if the user is not authenticated</p>                                                                                                                     |
| `error`               | *Error*             | <p>The latest error, if any, when authenticating a user. </p><p></p><p><code>error</code> is helpful for knowing when to display error messages to users.</p>                                                                                  |
| `login`               | *function*          | The [picket-js login function](https://docs.picketapi.com/picket-docs/reference/javascript-library-picket-js#login)                                                                                                                            |
| `logout`              | *function*          | The [picket-js logout function](https://docs.picketapi.com/picket-docs/reference/javascript-library-picket-js#logout)                                                                                                                          |
| `loginWithRedirect`   | *function*          | The [picket-js loginWithRedirect](https://docs.picketapi.com/picket-docs/reference/javascript-library-picket-js#login-with-redirect) function                                                                                                  |
| `loginWithPopup`      | *function*          | [The picket-js loginWithPopup](https://docs.picketapi.com/picket-docs/reference/javascript-library-picket-js#login-with-popup) function                                                                                                        |

### PicketRainbowAuthProvider

`PicketRainbowAuthProvider` allows you to use Picket for authentication and authorization with the [RainbowKit](https://www.rainbowkit.com/) modal.&#x20;

Interested in learning more? Go to the [Picket Authentication with RainbowKit](https://docs.picketapi.com/picket-docs/reference/integrations/picket-authentication-with-rainbowkit) integration page.

```typescript
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>
  );
}

```