# useTransferSubname

Hook for transferring subname.

## Import

```tsx
import { useTransferSubname } from "@ensforge/react";
```

## Usage

:::code-group
```tsx [component.tsx]
import { useTransferSubname } from "@ensforge/react";

function Component() {
  const mutation = useTransferSubname();

  return (
    <button
      disabled={mutation.isWaiting}
      onClick={() =>
        mutation.mutate({
          to: "value",
          name: "example.eth",
        })
      }
    >
      Submit
    </button>
  );
}
```

```tsx [provider.tsx]
// [!include ~/snippets/react/provider.tsx]
```
:::

## Parameters

```ts
import type { EnsMutationOptions } from "@ensforge/react";
```

The hook accepts an optional `EnsMutationOptions` object.

### retry

`false | Schedule<unknown, Failure> | undefined`

An Effect schedule used to retry typed failures. It defaults to `false`. Only retry writes that are
known to be safe and idempotent.

### onExit

`(exit: Exit<Success, Failure>, parameters: Parameters) => void`

Receives the complete Effect `Exit` and the exact mutation parameters after execution. Use
`Exit.match` or `Exit.isSuccess` to handle both outcomes without losing typed failures.

See [Mutation Options](/react/api/mutation-options) for schedules, provider defaults, and per-call
`onExit` handlers.

## Mutation Parameters

```ts
import type { TransferSubnameParameters } from "@ensforge/sdk/subnames";
```

### unsafe

`boolean | undefined`

Defaults to `false`. For ENSv2 registry transfers, opt in to bypass the safe-transfer restrictions
on non-emancipated registries and additional role assignees. Existing roles can retain access after
an unsafe transfer; use this only when that behavior is intended.

## Return Type

```ts
type Result = ReturnType<typeof useTransferSubname>;
```

Returns an [`EnsMutationResult`](/react/api/mutation-result).

| Property       | Description                                                    |
| -------------- | -------------------------------------------------------------- |
| `mutate`       | Starts the mutation and optionally reports its `Exit`.         |
| `mutateAsync`  | Starts the mutation and returns a Promise.                     |
| `mutateEffect` | Starts the mutation and returns an Effect with typed failures. |
| `data`         | Latest successful value, or `undefined`.                       |
| `error`        | Latest typed failure, an unexpected `Error`, or `null`.        |
| `cause`        | Complete Effect cause for the latest failure.                  |
| `isInitial`    | The mutation has not executed since creation or reset.         |
| `isWaiting`    | The mutation Effect is currently running.                      |
| `isSuccess`    | The latest execution succeeded.                                |
| `isFailure`    | The latest execution failed.                                   |
| `parameters`   | Parameters used by the latest execution.                       |
| `interrupt`    | Interrupts the active Effect.                                  |
| `reset`        | Restores the mutation to its initial state.                    |
| `result`       | Underlying Effect `AsyncResult`.                               |

## Effect Atom

```ts
import { createTransferSubnameMutationAtom } from "@ensforge/react/atoms";
import { sdk } from "./client";

const atom = createTransferSubnameMutationAtom(sdk);
```

The hook creates this atom with the SDK and registry supplied by [`EnsforgeProvider`](/react/api/ensforge-provider).

## Action

* [`transferSubname`](/core/api/actions/subnames/transfer-subname)
* [`sdk.subnames.transferSubname`](/sdk/api/subnames/transfer-subname)