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

Write data

Send ENS writes from components with useWrite or a named hook, track their steps and errors, and await the final result.

Use a write hook to send a transaction from an event handler. The hook tracks the write for you: its status, its steps, its result and its error. Use a testnet such as Sepolia and a name you own while you build.

Send a write

useSetRecords writes records to a name. Call mutate with the action's options. Writes need a wallet on the client. See Set up the provider.

Example (A Save Button)

Save.tsx
import { useSetRecords } from "@ensforge/react";

export function Save({ name }: { name: string }) {
  const { mutate, isPending, status, error } = useSetRecords();

  return (
    <>
      <button
        disabled={isPending}
        onClick={() => mutate({ name, texts: { url: "https://alice.xyz" } })}
      >
        {isPending ? "Saving..." : "Save"}
      </button>
      {status === "success" && <p>Saved</p>}
      {error && <p>{error.message}</p>}
    </>
  );
}

mutate returns nothing. The outcome lands in status, data and error. useSetRecords runs record.set, which resolves once the transaction is submitted. Use the …Sync action to wait for the receipt, shown below.

Pick a write hook

HookSends
useSetRecordsSets, changes or clears a name's records in one write.
useRegisterRegisters names: commit, wait the minimum age, then register.
useRenewRenews names.
useSetResolverPoints a name at a resolver.
useTransferNameTransfers a name to another account.
useCreateSubnameCreates a subname, optionally with records.
useSetPrimaryNameSets the signer's primary name.
useSignClaimSigns a primary-name claim once, to set it on other chains.
useMigrateMoves names from ENSv1 to ENSv2.

For any other write, use useWrite(action) with an action from @ensforge/sdk. Named hooks are presets of it.

What the hook returns

FieldMeaning
mutate(options)Sends the write. The outcome lands in status, data and error. Stable across renders.
mutateAsync(options)Sends the write and resolves with its own result, or rejects with its error. Stable across renders.
status"idle", "pending", "success" or "error", for the latest write started.
isPendingA write is running.
dataThe latest write's value, once it succeeded.
errorThe latest write's typed error.
stepsPlan events of the latest write: waiting, submitted, confirmed, failed.
reset()Clears the result and steps.

Each component gets its own state, so two buttons never share a result. The state follows the latest write started, while each mutateAsync settles with its own write.

Show progress

Multi-step writes, such as a registration (commit, wait, register), push an event to steps as each step changes. Each event names its step and its status. submitted events carry the transaction hashes, and failed events carry the error.

Example (Registering With Progress)

Register.tsx
import { useRegister } from "@ensforge/react";
import { Duration } from "@ensforge/sdk";

export function Register({ name }: { name: string }) {
  const { mutate, isPending, steps, error } = useRegister();

  return (
    <>
      <button
        disabled={isPending}
        onClick={() => mutate({ names: name, duration: Duration.years(1) })}
      >
        Register
      </button>
      <ol>
        {steps.map((event, index) => (
          <li key={index}>
            {event.step.description}: {event.status}
          </li>
        ))}
      </ol>
      {error && <p>{error.message}</p>}
    </>
  );
}

Await a write

Use mutateAsync to run code after the write, such as closing a dialog. It rejects with the action's error, so catch it.

Example (Waiting For The Receipt)

SaveAndClose.tsx
import { useWrite } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";

export function SaveAndClose({ name, onDone }: { name: string; onDone: () => void }) {
  const { mutateAsync, isPending } = useWrite(Actions.record.setSync);

  const save = async () => {
    try {
      await mutateAsync({ name, texts: { url: "https://alice.xyz" } });
      onDone();
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <button disabled={isPending} onClick={save}>
      Save
    </button>
  );
}

Actions.record.setSync resolves with receipts, once the transaction is mined. Actions.record.set resolves when it is submitted.

Start over

reset() clears status, data, error and steps. It never cancels a write in flight, because a sent transaction cannot be taken back. Their mutateAsync promises still settle, but they no longer update the state.

What refreshes afterwards

Once a write succeeds, every read of the names and accounts it touched refetches: chain reads once the transaction is mined, indexer reads once the indexer has caught up. Components that show the data update on their own. See Caching and refreshing.

To show what a write will do before the wallet prompt, see Preview before sending. For how plans work, see How writes work.

Was this page helpful?