Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeReact

React

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

30 hooks
Since v1.0.0View source

Generic hooks take any action; named hooks are presets of them for common actions. See Read data and Write data.

Named reads

HookDescription
useAddressReads the address a name points to, for ETH or another coin.
useAvailabilityChecks whether a name can be registered now.
useAvatarReads a name's avatar as an image URL, with NFT avatars resolved.
useMigrationStatusReads whether and how a name can move from ENSv1 to ENSv2.
useNameReads a name's state: owner, manager, expiry, resolver, registry and wrapper status.
useNameHistoryLists a name's events (registrations, transfers, record changes), page by page, from the indexer.
useNamesForAddressLists the names an address owns, manages or is the primary name of, page by page, from the indexer.
usePermissionsReads what an account may do with a name.
usePrimaryNameReads the primary name of an address, verified against its forward address.
useRecordsReads any mix of a name's records in one request; the result has exactly the requested fields.
useRegistrationPriceReads what registering names for a duration costs.
useSubnamesLists a name's subnames, page by page, from the indexer.
useTextReads one text record, such as url, avatar or com.twitter.

Named writes

HookDescription
useCreateSubnameCreates a subname, optionally with records.
useMigrateMoves names from ENSv1 to ENSv2.
useRegisterRegisters names: commit, wait the minimum age, then register, with every step in steps.
useRenewRenews names.
useSetPrimaryNameSets the signer's primary name.
useSetRecordsSets, changes or clears a name's records in one write.
useSetResolverPoints a name at a resolver.
useSignClaimSigns a claim to a primary name on L2s, with one signature and no transaction, for primaryName.set on each chain (or a relaying server).
useTransferNameTransfers a name to another account.

Provider

HookDescription
useEnsforgeThe client of the nearest EnsforgeProvider.

Reads

HookDescription
useInfiniteReadReads an indexer list page by page, such as a name's subnames or an account's names.
useReadReads with any ensforge action and keeps the result fresh.
useReadErrorResetThe reset handle of the nearest ReadErrorResetBoundary, or of the whole app without one.
useReadsRuns several reads at once; their RPC calls share the client's multicall batches.
useSuspenseReadReads with an action and suspends until the value is there; failures throw to the nearest error boundary.

Writes

HookDescription
usePreparePlans a write without sending it: its steps, calls and warnings, for a review screen before the wallet prompt.
useWriteSends any ensforge write and tracks it.

Types

InfiniteReadResult

What useInfiniteRead returns.

type InfiniteReadResult<page, error>
FieldTypeDescription
pagesreadonly page[]Every page loaded so far.
itemsreadonly ItemOf<page>[]The items of every page loaded so far, in order.
hasMorebooleanMore pages remain.
loadMore() => voidLoads the next page.
isLoadingbooleanThe first page is loading.
isLoadingMorebooleanA further page is loading.
errorerror
resultAsyncResult.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 };
FieldTypeDescription
pathstring
prepareAction

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; };
OptionTypeDefaultDescription
staleTimeDuration.InputAfter 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.
idleTTLDuration.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.
refetchIntervalDuration.InputRefetch on this interval while the read is in use, in the browser only.
refreshOnWindowFocusbooleanfalseRefetch when the window regains focus (respecting staleTime when set).
enabledbooleantrueRun the read. Passing undefined options also disables it, e.g. until a name is typed.
clientEnsforge.ClientClient to read with instead of the provider's.

ReadErrorReset

What ReadErrorResetBoundary and useReadErrorReset give.

type ReadErrorReset
FieldTypeDescription
reset() => voidMakes 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>
FieldTypeDescription
datavalueThe latest value, kept while refreshing.
errorerrorThe action's error when it failed.
status"idle" | "loading" | "success" | "error"idle while disabled, loading until the first result, then success or error.
isLoadingbooleanNo result yet and loading.
isRefreshingbooleanLoading again with a previous result shown.
resultAsyncResult.AsyncResult<value, error>The Effect Atom result, for AsyncResult.match.
refresh() => voidRefetches 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>
FieldTypeDescription
datavalue
isRefreshingbooleanLoading again with the current value shown.
refresh() => void

WriteResult

What useWrite returns.

type WriteResult<options, value, error>
FieldTypeDescription
mutate(options: options) => voidSends 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.
datavalueThe latest write's value, once it succeeded.
errorerror
status"idle" | "pending" | "success" | "error"Status of the latest write started.
isPendingboolean
stepsreadonly Plan.Event[]Progress of the latest write's plan: waiting, submitted, confirmed, failed.
resultAsyncResult.AsyncResult<value, error>
reset() => voidClears 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?