# 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](/picket-docs/reference/concepts/modal-themes.md).

### 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](/picket-docs/reference/libraries-and-sdks/javascript-library-picket-js.md#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](/picket-docs/reference/libraries-and-sdks/javascript-library-picket-js.md#login)                                                                                                                            |
| `logout`              | *function*          | The [picket-js logout function](/picket-docs/reference/libraries-and-sdks/javascript-library-picket-js.md#logout)                                                                                                                          |
| `loginWithRedirect`   | *function*          | The [picket-js loginWithRedirect](/picket-docs/reference/libraries-and-sdks/javascript-library-picket-js.md#login-with-redirect) function                                                                                                  |
| `loginWithPopup`      | *function*          | [The picket-js loginWithPopup](/picket-docs/reference/libraries-and-sdks/javascript-library-picket-js.md#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](/picket-docs/reference/integrations/picket-authentication-with-rainbowkit.md) 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>
  );
}

```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.picketapi.com/picket-docs/reference/libraries-and-sdks/react-sdk-picket-react.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.