> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useunitpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> How the @unitpay/react hooks work

`@unitpay/react` gives your app type-safe React hooks and components for building customer-facing billing UIs on **UnitPay** — the billing engine where **dollars and credits are both first-class**. One provider exposes a customer's subscriptions, invoices, payment methods, credit wallets, entitlements, and checkout.

## How hooks work

Every hook is built on [TanStack Query](https://tanstack.com/query) and reads from a single shared cache scoped to the current customer:

* **Auth** is a short-lived **portal-session token** (`portalToken`) minted on your server with [`@unitpay/node`](https://www.npmjs.com/package/@unitpay/node). The SDK attaches it as a bearer token and refreshes it for you — proactively (\~60s before it expires) and reactively (on a `401`). No secret keys ever reach the browser.
* **One fetch, many gates.** `useCustomer()` loads the customer and their entitlements once; `useEntitlement` and the `<FeatureGate>` components then resolve from that cache. Pass `requestedUsage` (or `{ fresh: true }`) when you need a live server check.
* **Mutations** (`useTopUp`, `useChangePlan`, …) resolve to a `SettleOutcome` describing how money moved, and auto-invalidate the affected queries. See [Settlement model](/react/settlement).

## Dollars and credits

Both billing paths are modeled side by side — subscriptions and invoices on the dollar side; wallets, grants, and the ledger on the credit side. Credit affordances render on every relevant surface regardless of whether the current plan uses credits.

## Installation

```bash theme={null}
npm install @unitpay/react react @tanstack/react-query
```

`react` (`>=18`) and `@tanstack/react-query` (`^5`) are peer dependencies — install one copy in your app so the SDK shares your `QueryClient`.

## Next steps

<CardGroup cols={2}>
  <Card title="UnitPayProvider" icon="plug" href="/react/provider">
    Wrap your app and configure the SDK.
  </Card>

  <Card title="useCustomer" icon="user" href="/react/customer">
    The customer's state and core billing actions.
  </Card>

  <Card title="Entitlement gates" icon="shield-halved" href="/react/entitlements-and-gates">
    Declarative access control components.
  </Card>

  <Card title="Next.js adapter" icon="server" href="/react/next-adapter">
    Proxy requests through your own backend.
  </Card>
</CardGroup>