# React

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

Look up every hook, component, server helper and atom of @ensforge/react, and the types the hooks take and return, with examples.

Source: https://ensforge.com/docs/reference/react

<ApiMeta summary="30 hooks" since="1.0.0" source="packages/react/src" />

Generic hooks take any action; named hooks are presets of them for common actions. See [Read data](/docs/react/read-data) and [Write data](/docs/react/write-data).

<Cards>
<Card title="Components" href="/docs/reference/react/components" description="EnsforgeProvider and the read error and hydration boundaries." />

<Card title="Server" href="/docs/reference/react/server" description="Prefetch reads on the server with @ensforge/react/server." />

<Card title="Atoms" href="/docs/reference/react/atoms" description="The atom layer of @ensforge/react/atoms that the hooks are built on." />
</Cards>

## Named reads [#named-reads]

| Hook | Description |
| --- | --- |
| [`useAddress`](/docs/reference/react/use-address) | Reads the address a name points to, for ETH or another coin. |
| [`useAvailability`](/docs/reference/react/use-availability) | Checks whether a name can be registered now. |
| [`useAvatar`](/docs/reference/react/use-avatar) | Reads a name's avatar as an image URL, with NFT avatars resolved. |
| [`useMigrationStatus`](/docs/reference/react/use-migration-status) | Reads whether and how a name can move from ENSv1 to ENSv2. |
| [`useName`](/docs/reference/react/use-name) | Reads a name's state: owner, manager, expiry, resolver, registry and wrapper status. |
| [`useNameHistory`](/docs/reference/react/use-name-history) | Lists a name's events (registrations, transfers, record changes), page by page, from the indexer. |
| [`useNamesForAddress`](/docs/reference/react/use-names-for-address) | Lists the names an address owns, manages or is the primary name of, page by page, from the indexer. |
| [`usePermissions`](/docs/reference/react/use-permissions) | Reads what an account may do with a name. |
| [`usePrimaryName`](/docs/reference/react/use-primary-name) | Reads the primary name of an address, verified against its forward address. |
| [`useRecords`](/docs/reference/react/use-records) | Reads any mix of a name's records in one request; the result has exactly the requested fields. |
| [`useRegistrationPrice`](/docs/reference/react/use-registration-price) | Reads what registering names for a duration costs. |
| [`useSubnames`](/docs/reference/react/use-subnames) | Lists a name's subnames, page by page, from the indexer. |
| [`useText`](/docs/reference/react/use-text) | Reads one text record, such as `url`, `avatar` or `com.twitter`. |

## Named writes [#named-writes]

| Hook | Description |
| --- | --- |
| [`useCreateSubname`](/docs/reference/react/use-create-subname) | Creates a subname, optionally with records. |
| [`useMigrate`](/docs/reference/react/use-migrate) | Moves names from ENSv1 to ENSv2. |
| [`useRegister`](/docs/reference/react/use-register) | Registers names: commit, wait the minimum age, then register, with every step in `steps`. |
| [`useRenew`](/docs/reference/react/use-renew) | Renews names. |
| [`useSetPrimaryName`](/docs/reference/react/use-set-primary-name) | Sets the signer's primary name. |
| [`useSetRecords`](/docs/reference/react/use-set-records) | Sets, changes or clears a name's records in one write. |
| [`useSetResolver`](/docs/reference/react/use-set-resolver) | Points a name at a resolver. |
| [`useSignClaim`](/docs/reference/react/use-sign-claim) | Signs a claim to a primary name on L2s, with one signature and no transaction, for `primaryName.set` on each chain (or a relaying server). |
| [`useTransferName`](/docs/reference/react/use-transfer-name) | Transfers a name to another account. |

## Provider [#provider]

| Hook | Description |
| --- | --- |
| [`useEnsforge`](/docs/reference/react/use-ensforge) | The client of the nearest `EnsforgeProvider`. |

## Reads [#reads]

| Hook | Description |
| --- | --- |
| [`useInfiniteRead`](/docs/reference/react/use-infinite-read) | Reads an indexer list page by page, such as a name's subnames or an account's names. |
| [`useRead`](/docs/reference/react/use-read) | Reads with any ensforge action and keeps the result fresh. |
| [`useReadErrorReset`](/docs/reference/react/use-read-error-reset) | The reset handle of the nearest [`ReadErrorResetBoundary`](/docs/reference/react/components#readerrorresetboundary), or of the whole app without one. |
| [`useReads`](/docs/reference/react/use-reads) | Runs several reads at once; their RPC calls share the client's multicall batches. |
| [`useSuspenseRead`](/docs/reference/react/use-suspense-read) | Reads with an action and suspends until the value is there; failures throw to the nearest error boundary. |

## Writes [#writes]

| Hook | Description |
| --- | --- |
| [`usePrepare`](/docs/reference/react/use-prepare) | Plans a write without sending it: its steps, calls and warnings, for a review screen before the wallet prompt. |
| [`useWrite`](/docs/reference/react/use-write) | Sends any ensforge write and tracks it. |

## Types [#types]

### `InfiniteReadResult` [#infinitereadresult]

What [`useInfiniteRead`](/docs/reference/react/use-infinite-read) returns.

```ts
type InfiniteReadResult<page, error>
```

| Field | Type | Description |
| --- | --- | --- |
| `pages` | `readonly page[]` | Every page loaded so far. |
| `items` | `readonly ItemOf<page>[]` | The items of every page loaded so far, in order. |
| `hasMore` | `boolean` | More pages remain. |
| `loadMore` | `() => void` | Loads the next page. |
| `isLoading` | `boolean` | The first page is loading. |
| `isLoadingMore` | `boolean` | A further page is loading. |
| `error` | `error` |  |
| `result` | `AsyncResult.AsyncResult< { readonly done: boolean; readonly items: readonly page[] }, error >` |  |

### `PreparableAction` [#preparableaction]

A write action, with the `.prepare` that plans it.

```ts
type PreparableAction = Action & { readonly prepare: Action };
```

| Field | Type | Description |
| --- | --- | --- |
| `path` | `string` |  |
| `prepare` | `Action` |  |

### `ReadConfig` [#readconfig]

Settings of a read hook: its freshness, whether it runs, and an optional client.

```ts
type ReadConfig = Freshness & { /** * Run the read. Passing `undefined` options also disables it, e.g. until a name is typed. * * @default true */ readonly enabled?: boolean | undefined; /** Client to read with instead of the provider's. */ readonly client?: Ensforge.Client | undefined; };
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `staleTime` | `Duration.Input` |  | After this long, the next mount or window focus refetches in the background while the cached value is shown (stale-while-revalidate). `Duration.infinity` never does. Without it, a value hydrated from the server is stale after 30 seconds; a failed read is always stale, so a remount retries it. |
| `idleTTL` | `Duration.Input \| "forever"` | `"1 minute"` | How long an unused read stays cached; `"forever"` or `Duration.infinity` keeps it. With hooks of several settings, the longest applies. |
| `refetchInterval` | `Duration.Input` |  | Refetch on this interval while the read is in use, in the browser only. |
| `refreshOnWindowFocus` | `boolean` | `false` | Refetch when the window regains focus (respecting `staleTime` when set). |
| `enabled` | `boolean` | `true` | Run the read. Passing `undefined` options also disables it, e.g. until a name is typed. |
| `client` | `Ensforge.Client` |  | Client to read with instead of the provider's. |

### `ReadErrorReset` [#readerrorreset]

What [`ReadErrorResetBoundary`](/docs/reference/react/components#readerrorresetboundary) and [`useReadErrorReset`](/docs/reference/react/use-read-error-reset) give.

```ts
type ReadErrorReset
```

| Field | Type | Description |
| --- | --- | --- |
| `reset` | `() => void` | Makes the reads below read again the failures they threw to an error boundary. Call it when the boundary resets; a failure is rethrown until then. |

### `ReadResult` [#readresult]

What a read hook returns.

```ts
type ReadResult<value, error>
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | `value` | The latest value, kept while refreshing. |
| `error` | `error` | The action's error when it failed. |
| `status` | `"idle" \| "loading" \| "success" \| "error"` | `idle` while disabled, `loading` until the first result, then `success` or `error`. |
| `isLoading` | `boolean` | No result yet and loading. |
| `isRefreshing` | `boolean` | Loading again with a previous result shown. |
| `result` | `AsyncResult.AsyncResult<value, error>` | The Effect Atom result, for `AsyncResult.match`. |
| `refresh` | `() => void` | Refetches the read. |

### `ReadSpec` [#readspec]

One read of [`useReads`](/docs/reference/react/use-reads): an action and its options.

```ts
type ReadSpec = readonly [action: Action, options: unknown];
```

### `ReadsResult` [#readsresult]

Results of [`useReads`](/docs/reference/react/use-reads), in the order of the reads.

```ts
type ReadsResult<reads extends readonly ReadSpec[]> = { readonly [index in keyof reads]: reads[index] extends readonly [ infer action extends Action, unknown, ] ? ReadResult<ActionValue<action>, ActionError<action>> : never; };
```

### `SuspenseReadResult` [#suspensereadresult]

What [`useSuspenseRead`](/docs/reference/react/use-suspense-read) returns: the value is always there.

```ts
type SuspenseReadResult<value>
```

| Field | Type | Description |
| --- | --- | --- |
| `data` | `value` |  |
| `isRefreshing` | `boolean` | Loading again with the current value shown. |
| `refresh` | `() => void` |  |

### `WriteResult` [#writeresult]

What [`useWrite`](/docs/reference/react/use-write) returns.

```ts
type WriteResult<options, value, error>
```

| Field | Type | Description |
| --- | --- | --- |
| `mutate` | `(options: options) => void` | Sends the write; the outcome lands in `status`, `data` and `error`. Stable across renders. |
| `mutateAsync` | `(options: options) => Promise<value>` | Sends the write and resolves with its own result, or rejects with its error, even when later writes start while it runs. Stable across renders. |
| `data` | `value` | The latest write's value, once it succeeded. |
| `error` | `error` |  |
| `status` | `"idle" \| "pending" \| "success" \| "error"` | Status of the latest write started. |
| `isPending` | `boolean` |  |
| `steps` | `readonly Plan.Event[]` | Progress of the latest write's plan: `waiting`, `submitted`, `confirmed`, `failed`. |
| `result` | `AsyncResult.AsyncResult<value, error>` |  |
| `reset` | `() => void` | Clears the result and steps. Writes in flight are not interrupted (a sent transaction cannot be taken back): their `mutateAsync` promises still settle, but they no longer update the state. Stable across renders. |