Javascript Hooks

LoginRadius provides a JavaScript Hooks system to alter or augment authentication forms and processes by intercepting lifecycle, configuration, messages, and events. Use hooks to customize validation, captcha, events, and error messages at runtime. Always register hooks before calling LRObject.init(...) so they apply to the forms and actions you render.

Core Concepts

// Hook API
LRObject.$hooks.register(name, callback, priority); // add a handler
LRObject.$hooks.call(name, ...args);               // invoke a hook by name

• Register vs Call: use register for lifecycle/event callbacks; use call for configuration-style hooks (labels, placeholders, validation rules, messages, captcha).
• Priority: optional priority lets you control execution order when multiple handlers exist under the same hook name.
• Scope: handlers receive the action name (e.g., login, registration, profileeditor) so you can target specific forms.

Supported Hooks

Configuration/Presentation:

• customizeFormLabel (deprecated in V3; prefer Common Options / Admin Console)
• customizeFormPlaceholder (deprecated in V3; prefer Common Options / Admin Console)
• setButtonsName (deprecated in V3; prefer Common Options / Admin Console)
• formAttributes (deprecated in V3)
• buttonAttributes
• defaultChoiceOption
• customizeElementTitle
• passwordMeterConfiguration
• setLocaleBasedInfo (prefer Admin Console localization)

Validation & Messages:

• formValidationRules
• mapValidationMessages
• mapErrorMessages

Captcha:

• addFormCaptcha
• addFormCaptchaExecute

Lifecycle & Events:

• beforeInit
• beforeFormRender
• afterFormRender
• afterValidation
• startProcess
• endProcess
• socialLoginFormRender
• getCurrentActionOptions
• addEventOnElement
• eventCalls

Register Order

// 1) lifecycle hooks
LRObject.$hooks.register('beforeInit', function (action) {
  // runs before any action initializes
});
LRObject.$hooks.register('startProcess', function (name) {
  // called when a form starts rendering
});
LRObject.$hooks.register('endProcess', function (name) {
  // called when a form finishes submitting
});

// 2) form presentation hooks
LRObject.$hooks.call('customizeFormLabel', {
  emailid: 'Email Address',
  password: 'Password'
});
LRObject.$hooks.call('customizeFormPlaceholder', {
  emailid: 'you@example.com',
  password: 'At least 8 characters'
});
LRObject.$hooks.call('setButtonsName', {
  login: 'Login',
  registration: 'Create Account'
});

// 3) validation hooks
LRObject.$hooks.call('formValidationRules', {
  emailid: 'required|valid_email',
  password: 'required|min_length[8]'
});

// 4) events
LRObject.$hooks.call('onAuthSuccess', function (response) {
  // handle token, redirect, fetch profile, etc.
});
LRObject.$hooks.call('onAuthError', function (errors) {
  // surface validation or API errors
});

Deprecated Hooks in V3 — use Common Options

Static UI customizations should be configured centrally rather than via runtime hooks. Prefer Common Options and Admin Console configuration for labels, placeholders, and button names.

• Deprecated: customizeFormLabel, customizeFormPlaceholder, setButtonsName, formAttributes

Lifecycle Hooks

• beforeInit(action): run code before an action initializes.
• startProcess(name): called when the target form starts rendering.
• endProcess(name): called when a form is submitted.
• beforeFormRender(name, schema): inspect/adjust schema before render.
• afterValidation(name): invoked after client validation fails.
• afterFormRender(name, schema): run code after any form is rendered.

Example:

LRObject.$hooks.register('beforeFormRender', function (name, schema) {
  if (name === 'twofaemailotp') {
    LRObject.$hooks.call('setButtonsName', {
      twofaemailotp: 'Verify Email OTP',
      resendotp: 'Resend verification code'
    });
  }
});
LRObject.$hooks.register('afterFormRender', function (name) {
  // attach events or analytics once elements exist
});

Validation Rules

Use formValidationRules to enforce per‑field rules. Common rules:

• required
• valid_email
• min_length[integer] / max_length[integer]
• exact_length[integer]
• matches[fieldName] (e.g., confirmpassword matches password)
• integer / numeric
• is_natural / is_natural_no_zero
• custom_validation[<regex>###<error message>]

Examples:

// Confirm password must match
LRObject.$hooks.call('formValidationRules', {
  password: 'required|min_length[8]',
  confirmpassword: 'matches[password]'
});

// Strong password policy
LRObject.$hooks.call('formValidationRules', {
  password:
    'custom_validation[^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[`~!@#$%^&+=])[A-Za-z\\d`~!@#$%^&+=]{8,}$###Password must contain 8+ chars, upper, lower, number, and special]'
});

// Custom validation messages
LRObject.$hooks.call('mapValidationMessages', [
  { rule: 'required', message: 'The %s field is required.' },
  { rule: 'valid_email', message: 'The %s field must be a valid email address.' },
  { rule: 'min_length', message: 'The %s field must be at least %s characters in length.' },
  { rule: 'max_length', message: 'The %s field must not exceed %s characters in length.' },
  { rule: 'matches', message: 'The %s field does not match the %s field.' }
]);

Captcha Hooks

Render a captcha in a specific container and receive its response via callback.

var captchaHandle = function (key) { console.log(key); };
LRObject.$hooks.call('addFormCaptcha', 'captcha-container', captchaHandle);

// If using Invisible reCAPTCHA or Tencent Captcha, expose the handler globally
window.captchaHandle = captchaHandle;

// Execute programmatic captcha (e.g., Invisible)
LRObject.$hooks.call('addFormCaptchaExecute', function () {
  // programmatically trigger captcha where supported
});

Events & Error Handling

• onAuthSuccess(response): handle successful authentication; check response.access_token.
• onAuthError(errors): handle errors; display or log.
• mapErrorMessages: customize error strings by error codes.
• addEventOnElement: attach custom events to generated form elements.

// Auth events
LRObject.$hooks.call('onAuthSuccess', function (response) {
  if (response && response.access_token) {
    // redirect or fetch profile
  }
});
LRObject.$hooks.call('onAuthError', function (errors) {
  // surface validation or API errors
});

// Map error messages by code
LRObject.$hooks.call('mapErrorMessages', [
  { code: 966, message: 'Email is not formatted correctly.' },
  { code: 967, message: 'Email format looks incorrect.' },
  { code: 1198, message: 'Your account encountered an issue. Please try again.' }
]);

// Attach events to a specific element
LRObject.$hooks.call('addEventOnElement', {
  selector: '#registration-container button[type="submit"]',
  event: 'click',
  handler: function () { console.log('Submit clicked'); }
});

Action Names Reference

These action names may be passed to lifecycle hooks and vary by features enabled in Dashboard:

• login, registration, forgotpassword, resetpassword, otplogin, passwordlesslogin
• verifyemail, resendemailverification, addemail, removeemail
• twofaotp, sendotp, resendotp, createtwofactorauthentication, disablegoogleauthenticator, disableotpauthenticator, backupcode, backupcodebutton
• changephone, updatephone, changenumber, changeusername, changepassword
• profileeditor, progressiveprofiling, acceptprivacypolicy, validatecode, onetouchlogin, smartlogin, updatesecurityquestion, resetpwdbysecq

Note: Only actions relevant to enabled features will trigger.

Best Practices

• Register hooks before calling LRObject.init.
• Prefer Admin Console for text and localization; avoid localization hooks in V3.
• Implement server‑side validation and rate limiting in addition to client rules.
• Scope custom code to specific name values to avoid unintended changes.
• Consider hook cleanup/unregistering (if supported) when tearing down views.

Related

• Quickstart: /deployment/js-libraries/v3/quickstart/
• Components: /deployment/js-libraries/v3/components/
• SDK Constructor: /deployment/js-libraries/v3/sdk-constructor/