# Update User Email Component

PropelAuth's Update Email component allows you to customize the update email flow in your app.

## Update Email

New Email

Confirm Password

Update Email

---

## [Shadcn Installation](https://ui.propelauth.com/account-page-components/update-email#shadcn-installation)

Install this component from our [shadcn registry](https://ui.propelauth.com/getting-started/component-registry).

```bash
npx shadcn@latest add https://components.propelauth.com/r/update-email.json
```

---

# Reference APIs

These are the APIs that are used by the above component. You can use these APIs directly in your own code.

## [updateEmail](https://ui.propelauth.com/account-page-components/update-email#update-email)

Starts the update email flow by sending a confirmation email to the user. If the user accepts, their email will be updated.

## Arguments

- Name `new_email`  
  **Type** string  
  **Description** The email address the user wants to change their email to.
- Name `password`  
  **Type** string  
  **Description** An optional argument to check if the user can provide the correct password. Required if the user has a password set.

## Response Functions

The response object has a **handle** function that you can use to handle the response. These functions can be async, and you can return values from them.

- Name `success`  
  **Description** Successful request.
- Name `cannotChangeEmailDueToOrgMembership`  
  **Description** User belongs to an organization that enforces an email domain restriction.
- Name `rateLimit`  
  **Description** Too many requests made for this specific user to update their email.
- Name `emailChangeDisabled`  
  **Description** 'Allow users to change their email' disabled in PropelAuth dashboard.
- Name `failedToSendEmail`  
  **Description** There was an error in sending the user the confirmation email.
- Name `incorrectPassword`  
  **Description** The user provided an incorrect password.
- Name `userAccountLocked`  
  **Description** The user's account is locked.
- Name `badRequest`  
  **Description** Incorrect arguments given.
- Name `unauthorized`  
  **Description** The user is not logged in.
- Name `unexpectedOrUnhandled`  
  **Description** An unexpected error occurred.

### Request

```javascript
const { updateEmail } = useAuthFrontendApis()

const response = await updateEmail({
    new_email: 'test@example.com',
    password: 'password',
})
response.handle({
    success: () => {
        console.log('Email update confirmation sent successfully')
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    failedToSendEmail: (error) => {
        console.log('Failed to send email', error.user_facing_error)
    },
    incorrectPassword: (error) => {
        console.log('The user provided an incorrect password', error.user_facing_error)
    },
    userAccountLocked: (error) => {
        console.log('User account locked', error.user_facing_error)
    },
    rateLimit: (error) => {
        console.log('Rate limit error', error.user_facing_error)
    },
    emailChangeDisabled: (error) => {
        console.error('Email change disabled', error.user_facing_error)
    },
    cannotChangeEmailDueToOrgMembership: (error) => {
        console.log('Cannot change email due to org membership', error.user_facing_error)
    },
    unexpectedOrUnhandled(error) {
        console.log('Unexpected or unhandled error', error.user_facing_error)
    },
})
```

### Successful Response

```json
{}
```