# React (https://session-kit.pages.dev/docs/reference/react)

```ts
import { … } from "@monarcode/session-kit/react";
```

Guide: [Read the session in React](https://session-kit.pages.dev/docs/getting-started#4-read-the-session-in-react).

## Functions

### createAuthHooks

Creates React hooks typed for one auth client. Use it when an app has several clients: each call has its own context, so call it once per client. With one client, register it and use [`useAuth`](#useauth), [`useAuthClient`](#useauthclient) and [`AuthProvider`](#authprovider) instead.

### useAuth

Reads the current auth state, or the part `selector` picks, and re-renders when it changes. With a selector, it re-renders only when that part changes.

### useAuthClient

Returns the client of the nearest [`AuthProvider`](#authprovider), for actions such as `signIn` and `signOut`. It's typed by the client you register in `Register`, from `@monarcode/session-kit` ([`ProvidedAuth`](#providedauth)).

### useMirrorAuth

Creates a `createMirrorAuth` client once, from the session the page was rendered with, and keeps it in step with your server. Call it in the component that renders `AuthProvider`.

## Components

### AuthProvider

Gives a client to the hooks below it, and mounts it while rendered, which starts expiry timers and following other tabs. Render it once, around your app.

## Types

### AuthHooks

The provider and hooks [`createAuthHooks`](#createauthhooks) returns, typed for one client.

### AuthHooksOptions

Options for [`createAuthHooks`](#createauthhooks).

### AuthHooksOptions

Options for createAuthHooks.

| Prop         | Type       | Description                                                                                                                                                                                                                                                                                                         |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useClient?` | `function` | Finds the client some other way than `AuthProvider`, such as from a context of your own. It's called as a hook, inside every hook, on every render. The hooks then need no `AuthProvider`, so mount the client another way. Default: the client of the nearest `AuthProvider` from the same `createAuthHooks` call. |

### AuthProviderProps

Props for [`AuthProvider`](#authprovider), and for the one that [`createAuthHooks`](#createauthhooks) returns.

### AuthProviderProps

Props for AuthProvider, and for the one that
createAuthHooks returns.

| Prop        | Type        | Description                                                    |
| ----------- | ----------- | -------------------------------------------------------------- |
| `client`    | `Client`    | The client for this tree. On a server, create one per request. |
| `children?` | `ReactNode` | The tree that reads `client` through the hooks.                |

### AuthSource

What the React bindings need from an auth client: its `state`, and `mount` to start background work while rendered. A `createAuth` or `createMirrorAuth` client fits.

### ProvidedAuth

The client `AuthProvider` takes and `useAuthClient` returns: the one you register in `Register`, from `@monarcode/session-kit`.

### StateOf

The state type of a client: what `useAuth()` returns (`AuthState`).

### UseMirrorAuthOptions

Options for [`useMirrorAuth`](#usemirrorauth).

### UseMirrorAuthOptions

Options for useMirrorAuth.

| Prop       | Type       | Description                                                                                                                                                                                                                                                                                                       |
| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create`   | `function` | Creates the client from the session the page was rendered with. It's called once, on the first render.                                                                                                                                                                                                            |
| `session`  | `union`    | The session your server rendered this page with, or `null`. When a new server render brings another one, the client takes it.                                                                                                                                                                                     |
| `onChange` | `function` | Called when the session changes in the browser, such as after `signOut()` or in another tab. Make it render on the server again, so its redirects run: `router.refresh()` in Next.js, or `revalidate` from `useRevalidator()` in React Router. It can be a new function on each render: the latest one is called. |