# @humanity-org/react-sdk

{% hint style="info" %}
Not building in React, or need full OAuth control? → [humanity-org-connect-sdk](https://docs.humanity.org/build-with-humanity/build-with-the-sdk-api/humanity-org-connect-sdk "mention")
{% endhint %}

The `@humanity-org/react-sdk` is the official React integration for Humanity. It provides pre-built components and hooks for OAuth authentication and credential verification **with full Typescript typings** — reducing integration time from days to \~30 minutes.

{% hint style="warning" %}
ℹ️ **Node requirement:** Node 18 or higher.
{% endhint %}

## Installation

```bash
npm install @humanity-org/react-sdk
# or
yarn add @humanity-org/react-sdk
# or
pnpm add @humanity-org/react-sdk
```

**Peer dependencies** (install if not already present):

```bash
npm install react react-dom
```

***

## Prerequisites

Before integrating, you need a **Humanity client ID**. Register your application in the [Humanity Developer Portal](https://developers.humanity.org/) and note your:

* `clientId` — e.g. `hp_xxx`
* `redirectUri` — the OAuth callback URL you registered (e.g. `https://yourapp.com/callback`)

***

## Getting started

#### Step 1 — Wrap your app with `HumanityProvider`

Place `HumanityProvider` at the root of your application. All SDK components and hooks must be rendered inside it.

```tsx
import { HumanityProvider } from '@humanity-org/react-sdk';

function App() {
  return (
    <HumanityProvider
      clientId={process.env.HUMANITY_CLIENT_ID!}
      redirectUri={process.env.HUMANITY_REDIRECT_URI!}
    >
      {/* rest of your app */}
    </HumanityProvider>
  );
}
```

#### Step 2 — Add a login button

```tsx
import { HumanityConnect } from '@humanity-org/react-sdk';

function LoginPage() {
  return (
    <HumanityConnect
      scopes={['openid', 'profile.full', 'identity:read']}
      onSuccess={(result) => console.log('Logged in!', result)}
    />
  );
}
```

#### Step 3 — Gate content on verification

```tsx
import { useAuth, HumanityGate } from '@humanity-org/react-sdk';

function Dashboard() {
  const { user, isAuthenticated, logout } = useAuth();

  if (!isAuthenticated) return <p>Please log in</p>;

  return (
    <HumanityGate
      preset="is_21_plus"
      fallback={<p>Age verification required</p>}
    >
      <h1>Welcome, {user?.name}!</h1>
      <button onClick={logout}>Sign Out</button>
    </HumanityGate>
  );
}

```

***

## Sandbox vs Production

Use `environment="sandbox"` during development to test without real credentials:

```tsx
<HumanityProvider
  clientId="hp_xxx"
  redirectUri="http://localhost:3000/callback"
  environment="sandbox"
>
  <App />
</HumanityProvider>
```

{% hint style="warning" %}
⚠️ **Warning:** Register separate redirect URIs for sandbox and production in the [Developer Portal](https://developers.humanity.org).
{% endhint %}

***

## Token Storage

The `storage` prop controls where OAuth tokens are kept:

| Value            | Security | Persists on refresh |
| ---------------- | -------- | ------------------- |
| `memory`         | Highest  | No                  |
| `sessionStorage` | Medium   | No                  |
| `localStorage`   | Lower    | Yes                 |

`memory` is the default and recommended for most apps. Use `localStorage` only if you require persistence and understand the XSS risk (Cross-site Scripting).

***

{% hint style="success" %}
Need integration examples?. Head to [react-sdk-examples](https://docs.humanity.org/starter-templates-and-examples/sdk-integration-templates/react-sdk-examples "mention")
{% endhint %}