useUserUpdateRequest

Programmatically update the user profile

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

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	Custom user metadata fields - Store additional user information like preferences, settings, or custom attributes (maximum size of 2kb). See User Metadata for detailed usage and examples.

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. The metadata field is particularly powerful for storing custom user data such as user preferences, application-specific settings, or any additional attributes your app needs to track.

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 OTP 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'])

You can also update metadata fields by including them in the fields array:

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

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 or SMS 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 OTP 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.
isSmsVerificationRequired	boolean	A boolean indicating whether SMS verification is necessary after updating the user profile. If true, initiate the SMS verification process.
updateUserProfileResponse	object	An object containing the server response from the user profile update request.
missingFields	ProjectSettingsKyc[]	An array of items for each field that is required but was still not provided.
verifyOtp	(verificationToken: string) => Promise<object>	A scoped function for performing OTP verification, provided only if isEmailVerificationRequired or isSmsVerificationRequired is true. This function’s single argument, verificationToken, should be the email or SMS verification token received from the user.

The verifyOtp function does not trigger onOtpVerificationResult. This way, when it fails you can decide whether to try again or abort.

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' })

You can also update custom metadata fields by including them in the userFields object:

updateUser({
  email: '[e-mail]',
  alias: 'John Doe',
  metadata: {
    favoriteColor: 'blue',
    subscriptionTier: 'premium',
    lastLoginDate: '2024-01-15'
  }
})

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 verifyOtp 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 {
      isSmsVerificationRequired,
      isEmailVerificationRequired,
      updateUserProfileResponse,
      verifyOtp,
    } = 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 verifyOtp(verificationToken);
      // Handle successful email verification, e.g., show a success message or redirect
    } else if (isSmsVerificationRequired) {
      // Trigger the SMS verification process
      // Obtain the verificationToken from the user (e.g., from a user-input field)
      const verificationToken = 'user-provided-verification-token';
      await verifyOtp(verificationToken);
      // Handle successful SMS 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

Working with User Metadata

The useUserUpdateRequest hook provides powerful capabilities for managing custom user metadata. Metadata allows you to store additional user information beyond the standard profile fields, making it perfect for:

• User preferences: Store user settings, theme choices, or language preferences
• Application state: Track user progress, feature flags, or onboarding status
• Custom attributes: Store business-specific data like subscription tiers, referral codes, or custom user categories
• Integration data: Store external service IDs, webhook configurations, or API keys

Metadata Best Practices

• Size limit: Metadata is limited to 2KB total, so keep values concise
• Key naming: Use descriptive, lowercase keys with underscores (e.g., subscription_tier, last_login_date)
• Value types: Metadata supports strings, numbers, booleans, and nested objects
• Validation: Always validate metadata on your backend before storing

Example: Comprehensive Metadata Update

const handleMetadataUpdate = async () => {
  const result = await updateUser({
    metadata: {
      // User preferences
      theme: 'dark',
      language: 'en',
      notifications_enabled: true,

      // Application state
      onboarding_completed: true,
      feature_flags: ['beta_features', 'advanced_analytics'],

      // Business data
      subscription_tier: 'premium',
      referral_code: 'USER123',
      last_purchase_date: '2024-01-15'
    }
  });

  // Handle verification if required
  if (result.isEmailVerificationRequired) {
    // Show verification form
  }
};

Function unlinkUserEmail

The unlinkUserEmail function allows you to remove a verified email credential from a user’s profile.

Parameter	Type	Description
verifiedCredentialId	string	The JWT format identifier of the email credential to unlink.

Output

Returns UserProfile | undefined. Returns the updated user profile if successful, or undefined if the operation fails.

Example Usage

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

function UnlinkEmailButton({ verifiedCredentialId }) {
  const { unlinkUserEmail } = useUserUpdateRequest();

  const handleUnlink = async () => {
    const updatedProfile = await unlinkUserEmail({ verifiedCredentialId });
    
    if (updatedProfile) {
      console.log('Email unlinked successfully');
    }
  };

  return <button onClick={handleUnlink}>Unlink Email</button>;
}

Integration with useOtpVerificationRequest

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

To handle email or SMS verification in another view or component, you can directly use the useOtpVerificationRequest hook, which provides the verifyOtp function. Using both hooks together ensures a streamlined user experience while maintaining security and data integrity.