useUserUpdateRequest

Programmatically update the user profile

The useUserUpdateRequest hook is a custom React hook designed for updating user profile information in your application. It provides an easy-to-use interface for developers to securely modify various user properties. It can be used in scenarios where you want to allow users to update their profile information, such as when they edit their account settings, complete onboarding steps, or update their preferences.

This hook returns two different methods for your convenience:

• The first method, updateUserWithModal, is a higher-level option that leverages our modals to perform all information editing — and email verification — seamlessly with a single method call.
• The second method, updateUser, is a lower-level option that requires you to build your own UI for information editing and email verification, but still does all the heavy lifting for you.

UserFields interface

Both updateUser and updateUserWithFunction functions use objects with properties that match the UserFields interface. The UserFields interface includes the following properties:

Property	Description
email	The user’s email address.
alias	The user’s alias.
firstName	The user’s first name.
lastName	The user’s last name.
jobTitle	The user’s job title.
phoneNumber	The user’s phone number.
tShirtSize	The user’s t-shirt size.
team	The user’s team name.
country	The user’s country, using the standard ISO 3166-1 alpha-2 two-letter country code.
username	The user’s username.
metadata	The user’s metadata (maximum size of 2kb)

By providing an object following the UserFields interface, the updateUser function allows you to update the necessary properties in the user profile while ensuring the restricted properties remain untouched.

Function updateUserWithModal

The updateUserWithModal function, provided by the useUserUpdateRequest hook, allows you to conveniently and securely handle the entire process of user profile updates — including email verification when necessary — with a single method call.

This function is the higher-level option returned from the useUserUpdateRequest hook, and it actually uses updateUser internally.

When called, this function will open one of our modals and prompt the user for the new values. If email verification is required, it also prompts the user for the verification code.

Parameter	Type	Description
fields	(keyof UserFields)[]	An array of the properties’ names you want to update
options	{ title?: string; subtitle?: string; submitText?: string; }	Options to customize the modal’s text

Output

The updateUserWithModal function returns a Promise<UserFields>. It resolves if and only if all fields were successfully updated, and resolves to an object with the new values mapped to their fields. If email verification was required but failed, no fields are updated and the promise rejects.

If the promise rejects, it provides a helpful message explaining the reason.

One notable error cause is if you forget to previously enable one of the fields you are trying to update in your app’s dashboard.

As opposed to updateUser, updateUserWithModal does trigger onOtpVerificationResult.

Example Usage

A simple example of how to use this function to update a user’s email and alias:

updateUserWithModal(['email', 'alias'])

For a more complete example, the useUserUpdateRequest hook is imported and used in the UserProfileEdit component. The updateUserWithModal function is called with the fields array when the user requests a profile information update. If email verification is required, it is automatically handled by the function. Once the returned promise is resolved, you can handle the successful update, such as by showing a success message or redirecting the user to another page.

import { useUserUpdateRequest } from '@dynamic-labs/sdk-react-core';

function UserProfileEdit() {
  const { updateUserWithModal } = useUserUpdateRequest();

  const handleUpdate = (fields) => {
    updateUserWithModal(fields)
      .then((updatedFields) => {
        // Handle successful update, e.g., show a success message or redirect
      })
      .catch((errorMessage) => {
        // Handle failure, e.g., show an error message or redirect
      });
  };

  return (
    // Render your component with buttons to update your user's profile information
    // ...
  );
}

If you wish to know whether email or SMS verification was necessary for the update, and whether it succeeded/failed, you can subscribe to the event onOtpVerificationResult

Function updateUser

The updateUser function, provided by the useUserUpdateRequest hook, allows you to conveniently and securely handle user profile updates with new values directly, and also provides a method for email verification, when necessary.

Parameter	Type	Description
userFields	UserFields	An object containing the user properties you want to update — keys are the fields, values are the updated values

Output

The updateUser function returns an object with the following properties:

Property	Type	Description
isEmailVerificationRequired	boolean	A boolean indicating whether email verification is necessary after updating the user profile. If true, initiate the email verification process.
updateUserProfileResponse	object	An object containing the server response from the user profile update request.
verifyEmailFn	(verificationToken: string) => Promise<object>	A scoped function for verifying the user’s email, provided only if isEmailVerificationRequired is true. This function’s single argument, verificationToken, should be the email verification token received from the user.

The verifyEmailFn function does not trigger onOtpVerificationResult. This way, when it fails you can decide whether to try again or declare an actual “failure”.

Example Usage

A simple example of how to use this function to update a user’s email and alias:

updateUser({ email: '[e-mail]', alias: 'John Doe' })

For a more complete example, the useUserUpdateRequest hook is imported and used in the UserProfileEdit component. The updateUser function is called with the userFields object when the user saves their profile information. If email verification is required (isEmailVerificationRequired is true), the verifyEmailFn function is used to handle the email verification process. Once the email is verified or if email verification is not required, you can handle the successful update, such as by showing a success message or redirecting the user to another page.

import { useUserUpdateRequest } from '@dynamic-labs/sdk-react-core';

function UserProfileEdit() {
  const { updateUser } = useUserUpdateRequest();

  const handleSave = async (userFields) => {
    const {
      isEmailVerificationRequired,
      updateUserProfileResponse,
      verifyEmailFn,
    } = await updateUser(userFields);

    if (isEmailVerificationRequired) {
      // Trigger the email verification process
      // Obtain the verificationToken from the user (e.g., from a user-input field)
      const verificationToken = 'user-provided-verification-token';
      await verifyEmailFn(verificationToken);
      // Handle successful email verification, e.g., show a success message or redirect
    } else {
      // Handle successful update without email verification, e.g., show a success message or redirect
    }
  };

  return (
    // Render your component with user fields input and save button
    // ...
  );
}

Live preview

Integration with useOtpVerificationRequest

The useUserUpdateRequest hook is designed to work seamlessly with the useOtpVerificationRequest hook.

To handle email verification in another view or component, you can directly use the useOtpVerificationRequest hook, which provides the verifyOtp function. This allows you to verify a user’s email address after they update their email in their profile. Using both hooks together ensures a streamlined user experience while maintaining security and data integrity.