---
title: "useEmailChange"
description: "useEmailChange, auto-imported in the app: its options, return value and types."
canonical_url: "https://nuxt-backend.dev/docs/reference/api/use-email-change"
---
# useEmailChange

## Interfaces

### UseEmailChangeOptions

Defined in: [src/runtime/vue/composables/use-email-change.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts)

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="validateemail">
        
      </a>
      
       <code>
        validateEmail?
      </code>
    </td>
    
    <td>
      (<code>
        email
      </code>
      
      ) => <code>
        string
      </code>
      
       | <code>
        boolean
      </code>
    </td>
    
    <td>
      Gate the new address before any code is sent. Return <code>
        true
      </code>
      
       to accept, <code>
        false
      </code>
      
       for the default message, or a string for a custom one. Default: a basic shape check.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="onchanged">
        
      </a>
      
       <code>
        onChanged?
      </code>
    </td>
    
    <td>
      (<code>
        newEmail
      </code>
      
      ) => <code>
        unknown
      </code>
    </td>
    
    <td>
      Called once the account has moved to the new address.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### UseEmailChangeReturn

Defined in: [src/runtime/vue/composables/use-email-change.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts)

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="step">
        
      </a>
      
       <code>
        step
      </code>
    </td>
    
    <td>
      <code>
        Ref
      </code>
      
      <<a href="#emailchangestep">
        <code>
          EmailChangeStep
        </code>
      </a>
      
      >
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="newemail">
        
      </a>
      
       <code>
        newEmail
      </code>
    </td>
    
    <td>
      <code>
        Ref
      </code>
      
      <<code>
        string
      </code>
      
      >
    </td>
    
    <td>
      The address the account moves to.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="otp">
        
      </a>
      
       <code>
        otp
      </code>
    </td>
    
    <td>
      <code>
        Ref
      </code>
      
      <<code>
        string
      </code>
      
      >
    </td>
    
    <td>
      The code of the current step.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="pending">
        
      </a>
      
       <code>
        pending
      </code>
    </td>
    
    <td>
      <code>
        Ref
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="error">
        
      </a>
      
       <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        Ref
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="retryafter">
        
      </a>
      
       <code>
        retryAfter
      </code>
    </td>
    
    <td>
      <code>
        Ref
      </code>
      
      <<code>
        number
      </code>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      Seconds until a rate-limited step can be retried; <code>
        null
      </code>
      
       otherwise.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="emailvalid">
        
      </a>
      
       <code>
        emailValid
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      Whether <code>
        newEmail
      </code>
      
       passes <code>
        validateEmail
      </code>
      
       and differs from the current address.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="start">
        
      </a>
      
       <code>
        start
      </code>
    </td>
    
    <td>
      () => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Email a code to the current address → <code>
        confirm-current
      </code>
      
      .
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="confirmcurrent">
        
      </a>
      
       <code>
        confirmCurrent
      </code>
    </td>
    
    <td>
      () => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Check the current address's code, then email a code to the new one → <code>
        verify-new
      </code>
      
      .
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="verifynew">
        
      </a>
      
       <code>
        verifyNew
      </code>
    </td>
    
    <td>
      () => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Check the new address's code: the account moves to it → <code>
        done
      </code>
      
      .
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="reset">
        
      </a>
      
       <code>
        reset
      </code>
    </td>
    
    <td>
      () => <code>
        void
      </code>
    </td>
    
    <td>
      Back to <code>
        enter-email
      </code>
      
      , everything cleared.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-change.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

## Type Aliases

### EmailChangeStep

```ts
type EmailChangeStep = "enter-email" | "confirm-current" | "verify-new" | "done";
```

Defined in: [src/runtime/vue/composables/use-email-change.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts)

The email change, by code at both addresses:
`enter-email` → `start` emails a code to the current address →
`confirm-current` → `confirmCurrent` checks it and emails a code to the new
address → `verify-new` → `verifyNew` checks that one and moves the account →
`done`.

## Functions

### useEmailChange()

```ts
function useEmailChange(options?): UseEmailChangeReturn;
```

Defined in: [src/runtime/vue/composables/use-email-change.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-change.ts)

The headless email change behind `<ProfileSettings>`: a code from the
current address proves the person asking still holds it, a code from the
new address proves they hold that one too. No link is ever sent, so nobody
who merely opens an email can change the account.

Like `useLoginFlow`, a step machine that never rejects: a failed step
leaves `step` where it was and puts the reason in `error` (with the wait
of a 429 in `retryAfter`).

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="#useemailchangeoptions">
        <code>
          UseEmailChangeOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

#### Returns

[`UseEmailChangeReturn`](#useemailchangereturn)


## Sitemap

See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.