React
Look up every hook, component, server helper and atom of @ensforge/react, and the types the hooks take and return, with examples.
Generic hooks take any action; named hooks are presets of them for common actions. See Read data and Write data.
Components
EnsforgeProvider and the read error and hydration boundaries.
Server
Prefetch reads on the server with @ensforge/react/server.
Atoms
The atom layer of @ensforge/react/atoms that the hooks are built on.
Named reads
| Hook | Description |
|---|---|
useAddress | Reads the address a name points to, for ETH or another coin. |
useAvailability | Checks whether a name can be registered now. |
useAvatar | Reads a name's avatar as an image URL, with NFT avatars resolved. |
useMigrationStatus | Reads whether and how a name can move from ENSv1 to ENSv2. |
useName | Reads a name's state: owner, manager, expiry, resolver, registry and wrapper status. |
useNameHistory | Lists a name's events (registrations, transfers, record changes), page by page, from the indexer. |
useNamesForAddress | Lists the names an address owns, manages or is the primary name of, page by page, from the indexer. |
usePermissions | Reads what an account may do with a name. |
usePrimaryName | Reads the primary name of an address, verified against its forward address. |
useRecords | Reads any mix of a name's records in one request; the result has exactly the requested fields. |
useRegistrationPrice | Reads what registering names for a duration costs. |
useSubnames | Lists a name's subnames, page by page, from the indexer. |
useText | Reads one text record, such as url, avatar or com.twitter. |
Named writes
| Hook | Description |
|---|---|
useCreateSubname | Creates a subname, optionally with records. |
useMigrate | Moves names from ENSv1 to ENSv2. |
useRegister | Registers names: commit, wait the minimum age, then register, with every step in steps. |
useRenew | Renews names. |
useSetPrimaryName | Sets the signer's primary name. |
useSetRecords | Sets, changes or clears a name's records in one write. |
useSetResolver | Points a name at a resolver. |
useSignClaim | 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 | Transfers a name to another account. |
Provider
| Hook | Description |
|---|---|
useEnsforge | The client of the nearest EnsforgeProvider. |
Reads
| Hook | Description |
|---|---|
useInfiniteRead | Reads an indexer list page by page, such as a name's subnames or an account's names. |
useRead | Reads with any ensforge action and keeps the result fresh. |
useReadErrorReset | The reset handle of the nearest ReadErrorResetBoundary, or of the whole app without one. |
useReads | Runs several reads at once; their RPC calls share the client's multicall batches. |
useSuspenseRead | Reads with an action and suspends until the value is there; failures throw to the nearest error boundary. |
Writes
| Hook | Description |
|---|---|
usePrepare | Plans a write without sending it: its steps, calls and warnings, for a review screen before the wallet prompt. |
useWrite | Sends any ensforge write and tracks it. |
Types
InfiniteReadResult
What useInfiniteRead returns.
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
A write action, with the .prepare that plans it.
type PreparableAction = Action & { readonly prepare: Action };| Field | Type | Description |
|---|---|---|
path | string | |
prepare | Action |
ReadConfig
Settings of a read hook: its freshness, whether it runs, and an optional client.
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
What ReadErrorResetBoundary and useReadErrorReset give.
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
What a read hook returns.
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
One read of useReads: an action and its options.
type ReadSpec = readonly [action: Action, options: unknown];ReadsResult
Results of useReads, in the order of the reads.
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
What useSuspenseRead returns: the value is always there.
type SuspenseReadResult<value>| Field | Type | Description |
|---|---|---|
data | value | |
isRefreshing | boolean | Loading again with the current value shown. |
refresh | () => void |
WriteResult
What useWrite returns.
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. |
Was this page helpful?