@auth0/auth0-acul-js - v1.10.0
    Preparing search index...

    Class LoginEmailVerification

    LoginEmailVerification classdesc Manages interactions for the "login-email-verification" screen. This screen prompts the user to enter a one-time code sent to their email address to verify their identity during the login process.

    It provides methods to submit the entered code (continueWithCode) or to request a new code if the original one was not received or has expired (resendCode).

    Inherits from BaseContext to access shared authentication flow data like transaction state, client information, and internationalization texts.

    // How to use the LoginEmailVerification screen SDK:
    import LoginEmailVerification from '@auth0/auth0-acul-js/login-email-verification';

    // Instantiate the manager for the login email verification screen
    const loginEmailVerificationManager = new LoginEmailVerification();

    // Accessing screen-specific texts (e.g., for titles, labels, button texts)
    const screenTexts = loginEmailVerificationManager.screen.texts;
    const pageTitle = screenTexts?.title || 'Verify Your Email';
    const codePlaceholder = screenTexts?.codePlaceholder || 'Enter code here';

    // Accessing transaction errors from a previous attempt
    const transactionErrors = loginEmailVerificationManager.transaction.errors;
    if (transactionErrors && transactionErrors.length > 0) {
      transactionErrors.forEach(error => {
        console.error(`Error Code: ${error.code}, Message: ${error.message}`);
        // Display these errors to the user appropriately.
      });
    }

    // Example of handling code submission from a form
    async function onCodeSubmit(enteredCode: string) {
      try {
        await loginEmailVerificationManager.continueWithCode({ code: enteredCode });
        // On successful verification, Auth0 will typically redirect the user.
        // If there's a validation error (e.g., invalid code), the page will
        // re-render, and `loginEmailVerificationManager.transaction.errors` will be updated.
      } catch (e) {
        // This catch block is for unexpected errors during submission (e.g., network issues).
        console.error('An unexpected error occurred while submitting the code:', e);
      }
    }

    // Example of handling a resend code request
    async function onResendCodeClick() {
      await loginEmailVerificationManager.resendCode();
      // The page reloads, so any "code sent" message set here is lost.
      // On the reloaded page, check `loginEmailVerificationManager.transaction.errors`
      // for issues like "too-many-email".
    }

    Hierarchy

    • BaseContext
      • LoginEmailVerification

    Implements

    Index

    Constructors

    constructor

    Properties

    branding client countryCodes experiment organization prompt screen tenant transaction untrustedData user screenIdentifier

    Methods - Language

    changeLanguage

    Methods - Other

    continueWithCode getErrors resendCode resendManager

    Constructors

    Properties

    branding: Screens.BrandingMembers
    client: Screens.ClientMembers
    countryCodes: Screens.CountryCodesMembers

    Optional on the interface so existing implementors of BaseMembers (e.g. test mocks) keep compiling. Always populated at runtime by the BaseContext constructor.

    experiment: Screens.ExperimentMembers | null
    organization: Screens.OrganizationMembers
    prompt: Screens.PromptMembers
    screen: Screens.ScreenMembers
    tenant: Screens.TenantMembers
    transaction: Screens.TransactionMembers
    untrustedData: Screens.UntrustedDataMembers
    user: Screens.UserMembers
    screenIdentifier: string = ScreenIds.LOGIN_EMAIL_VERIFICATION

    The unique identifier for the Login Email Verification screen. This static property is used by the SDK's BaseContext to ensure that the class is instantiated in the correct screen context.

    Methods - Language

    • Utility Feature

      Changes the language/locale for the current authentication flow.

      This method triggers a language change by submitting the new locale preference to the server with the 'change-language' action. The language change will cause the current screen to re-render with the new locale.

      Parameters

      • options: Screens.LanguageChangeOptions

        Language change options including the target language code

        Options for changing the language/locale during the authentication flow

        • [key: string]: string | number | boolean | undefined

          Additional custom fields to be submitted along with the language change. Custom fields should be prefixed with 'ulp-'.

        • language: string

          Short language name (locale code) to be set (e.g., 'en', 'fr', 'es').

        • Optionalpersist?: "session"

          Defines persistence scope for the language preference. Currently only 'session' is supported.

          'session'

      Returns Promise<void>

      A promise that resolves when the form submission is complete

      import LoginId from "@auth0/auth0-acul-js/login-id";

      const loginManager = new LoginId();

      // Change language to French
      await loginManager.changeLanguage({
        language: 'fr',
        persist: 'session'
      });

      import LoginPassword from "@auth0/auth0-acul-js/login-password";

      const loginPasswordManager = new LoginPassword();

      // Change language to Spanish with additional custom data
      await loginPasswordManager.changeLanguage({
        language: 'es',
        persist: 'session',
        'ulp-custom-field': 'custom-value'
      });
      • This method is available on all screen instances that extend BaseContext
      • The language must be one of the enabled locales configured in your Auth0 tenant
      • The screen will automatically re-render with the new language after submission
      • Custom fields can be included and will be accessible in the Post Login Trigger

    Methods - Other

    • Submits the email verification code entered by the user to Auth0. This method prepares and posts the form data, including the verification code and the required action: "default", to the /u/login-email-verification endpoint.

      Parameters

      Returns Promise<void>

      A promise that resolves once the form submission is initiated. Typically, a successful submission leads to a server-side redirect. If the code is incorrect or an error occurs, the page will re-render, and this.transaction.errors will be populated.

      If the payload.code is missing or not a string. It can also throw if FormHandler encounters an issue during submission (e.g. network error). Auth0 validation errors (e.g. "invalid-code") are not thrown as JS errors but are made available in this.transaction.errors post-operation.

      const manager = new LoginEmailVerification();
      // Assuming 'userInputCode' is a string obtained from a form input
      manager.continueWithCode({ code: userInputCode })
        .catch(err => {
          // Handle unexpected submission errors
          displayGlobalError("Could not submit your code. Please try again.");
        });
      // After the operation, check manager.transaction.errors for validation messages.

    • Requests Auth0 to send a new verification code to the user's email address. This is typically used when the user didn't receive the original code, or it has expired.

      Parameters

      Returns Promise<void>

      A promise that resolves once the form is submitted, before the page reloads. It doesn't confirm that a new code was sent.

      Submits a form POST with action: "resend-code". Auth0 responds by rendering this screen again, so the browser reloads the page and the current JavaScript context, including component state and timers, is lost.

      Code after await resendCode() may still run, but anything it sets up, such as a "code sent" message or a countdown, is gone after the reload. Server-side errors, such as rate limits (too-many-email), appear in transaction.errors on the reloaded page. They don't reject the returned promise.

      To add a cooldown between resends, use resendManager(). It stores its countdown in localStorage, so the countdown survives the reload.

      import LoginEmailVerification from '@auth0/auth0-acul-js/login-email-verification';

      const loginEmailVerification = new LoginEmailVerification();
      await loginEmailVerification.resendCode();
      // The page reloads. On the new page, check `transaction.errors` for issues
      // such as `too-many-email`.
    • Utility Feature

      Gets resend functionality with timeout management for this screen

      Parameters

      Returns Screens.ResendControl

      ResendControl object with startResend method

      import LoginEmailVerification from '@auth0/auth0-acul-js/login-email-verification';

      const loginEmailVerification = new LoginEmailVerification();
      const { startResend } = loginEmailVerification.resendManager({
        timeoutSeconds: 15,
        onStatusChange: (remainingSeconds, isDisabled) => {
          console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
        },
        onTimeout: () => {
          console.log('Resend is now available');
        }
      });

      // Call startResend when user clicks resend button
      startResend();

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods - Language
    Methods - Other