Options

The options object is passed once when you instantiate the SDK and controls global behavior across all authentication flows. It covers core settings, transactional email/SMS templates, localization, theming, CAPTCHA, and UI messaging.

The fields documented here apply to both the LoginRadius JavaScript SDK and the LoginRadius React SDK — in the React SDK they are passed via the options prop on LoginRadiusProvider.

Configuration

Instantiate the SDK once at app startup and pass the credentials and any overrides you need. The minimum required field is apiKey.

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>", // required
  verificationUrl: "https://yourdomain.com/verify",
  resetPasswordUrl: "https://yourdomain.com/reset-password",
});

note

Enable CAPTCHA in the LoginRadius Dashboard before going live. CAPTCHA protects your authentication flows from automated abuse — turn on CAPTCHA from Console by navigating to Security → Attack Protection → Bot Protection.

Reference

The following table lists every field the SDK accepts.

note

Only apiKey is required at instantiation. sott is conditional — needed for registration only when Bot Protection (Captcha) is not enabled in the Admin Console (see the sott row for details). Every other field is optional and falls back to the documented default or your Admin Console configuration.

Option	Type	Description
`apiKey`	`string`	Your LoginRadius API key — the primary identifier for your application, required for all SDK operations.
`sott`	`string`	Secure One-Time Token that authorizes registration from the browser. Required only when Bot Protection (Captcha) is not enabled in the Admin Console — when Captcha is on, omit `sott`. Generate the token from Tenant Settings → API Configuration → SOTT, inject it server-side at page render, and never hardcode it in client bundles.
`verificationUrl`	`string`	The URL that LoginRadius sends email verification links to. The SDK appends the verification token as a query parameter.
`callbackUrl`	`string`	The URL the Hub redirects back to after social login. Defaults to `window.location.href` (stripped of query parameters) on SDK initialization.
`callbackInsideSameWindow`	`boolean`	Controls whether social login opens a popup window (`false`, default) or navigates the current tab to the provider (`true`). See [Social login callback following options. Defaults to `false`.
`callbackType`	`'' \| 'hash' \| 'querystring'`	Controls how the social login token is delivered back to your app. Works together with `callbackInsideSameWindow`. See [Social login callback following options. Defaults to `''`.
`resetPasswordUrl`	`string`	The URL included in password reset emails. LoginRadius appends a reset token to this URL.
`customDomain`	`string`	Override the default LoginRadius CDN domain with a custom domain configured in your Admin Console. Useful for white-label deployments.
`apiCustomDomain`	`string`	Override the default LoginRadius API domain. Use this when your environment routes API traffic through a custom domain or reverse proxy.
`projectionFields`	`string[]`	Specify which user profile fields the API returns. Reduces payload size and limits exposure of unnecessary profile data — recommended as a least-privilege practice.
`isMobile`	`boolean`	Signals to the SDK that it is rendering in a mobile context, adjusting certain UI behaviors and form interactions accordingly. Defaults to `false`.
`enableIdentifierCheck`	`boolean`	Enables an Identifier Availability check during the Register flow, so the chosen identifier (email, username, or phone) is verified as available before registration proceeds. The check is not mandatory. When `false` or omitted, the check is skipped and users can register without verifying identifier availability. Defaults to `false`.
`templateName`	`string`	Specifies a brand configured in the Admin Console. The SDK automatically retrieves and applies the default styles associated with that brand — no manual CSS import required.
`styleName`	`string`	Applies a specific style variant within the brand defined by `templateName` (which is required). The style must be configured (but not necessarily deployed) in the Admin Console.
`disableLocalization`	`boolean`	The SDK detects the browser's language and applies the corresponding locale automatically. Set to `true` to disable browser-based localization and enforce a fixed language. Defaults to `false`.
`disableSocialLocalization`	`boolean`	Suppresses the `lang` locale parameter the SDK appends to outbound social-provider login URLs, independent of the SDK's own UI localization. See disableSocialLocalization below. Defaults to `false`.
`localizationConfig`	`object`	Override the SDK's default text — labels, placeholders, validation messages, and button text. See Localization for details.
`captchaLanguage`	`string`	Applies a language locale to all CAPTCHA providers configured in the Admin Console (reCAPTCHA v2, reCAPTCHA v3, hCaptcha). Accepts standard BCP 47 language codes. Replaces the V2 `v2RecaptchaLanguage` parameter.
`v2Recaptcha`	`boolean`	Enables Google reCAPTCHA v2 on forms (must first be enabled in the Admin Console). By default reCAPTCHA v2 loads in invisible mode; set to `true` to render the visible checkbox widget. Defaults to `false`.
`successMessageConfig`	`object`	Controls how success messages are displayed after form actions. See successMessageConfig below.
`errorMessageConfig`	`object`	Controls how error messages are displayed when form actions fail. See errorMessageConfig below.
`resendRestriction`	`object`	Sets a per-flow cooldown timer (in seconds) on the resend button across components. After a resend click, the button is disabled and shows a countdown, then reactivates when the timer elapses. See resendRestriction below.
`contactusUrl`	`string`	A URL linked from certain error states to direct users to your support or contact page.
`formValidationMode`	`'onChange' \| 'onBlur'`	Controls when inline validation errors appear as users fill out SDK forms. See formValidationMode below. Defaults to `'onBlur'`.
`displayPasswordStrength`	`object`	Shows a live password-strength checklist beside the field where a user creates a new password, marking each password-policy requirement as met or unmet while the user types. Requires `isEnabled: true`. See displayPasswordStrength below. Defaults to disabled.
`defaultFieldValues`	`object`	Pre-populates sign-up and profile fields with values you choose, instead of every field starting empty. Keyed by exact field name. See defaultFieldValues below. Defaults to `{}` (no field is pre-filled).
`advancedFieldSingletonConfig`	`object`	Renders specific advanced field groups (Addresses, Phone Numbers, and similar repeatable sections) as a single non-repeatable instance instead of a list. Keyed by group name. See advancedFieldSingletonConfig below. Defaults to `{}` (every group stays repeatable).
`prefillWorkflowIdentifier`	`boolean`	Carries an identifier the user entered on an earlier Identity Orchestration workflow step into the matching field on later steps of the same workflow. Matching is by form node type, so only `email`, `phone`, `phonenumber`, and `username` nodes are pre-filled. See prefillWorkflowIdentifier below. Defaults to `false`.
`verificationEmailTemplate`	`string`	Template name for email address verification messages.
`welcomeEmailTemplate`	`string`	Template name for the email sent to users upon successful registration.
`resetPasswordEmailTemplate`	`string`	Template name for password reset request emails.
`resetPasswordConfirmationEmailTemplate`	`string`	Template name for the email sent after a password reset is completed.
`addEmailTemplate`	`string`	Template name for adding a secondary email address.
`deleteUserEmailTemplate`	`string`	Template name for the email sent when an account deletion is requested.
`onetouchLoginEmailTemplate`	`string`	Template name for one-touch (magic link) login emails.
`passwordlessLoginEmailTemplate`	`string`	Template name for passwordless login via email link.
`passwordlessLoginSMSTemplate`	`string`	Template name for passwordless login via SMS OTP.
`smsTemplate2FA`	`string`	Template name for two-factor authentication SMS OTP.
`smsTemplate2FAWelcome`	`string`	Template name for the welcome SMS sent after 2FA enrollment.
`smsTemplatePhoneVerification`	`string`	Template name for phone number verification SMS.
`smsTemplateWelcome`	`string`	Template name for the general SMS welcome message.
`smsTemplateOneTouchLogin`	`string`	Template name for one-touch login SMS.
`smsTemplateOneTouchLoginWelcome`	`string`	Template name for the welcome SMS after one-touch login.
`smsTemplateForgot`	`string`	Template name for forgot-password SMS OTP.
`smsTemplateUpdatePhone`	`string`	Template name for the SMS sent when updating a phone number.
`smsTemplateInstantOTPLogin`	`string`	Template name for instant OTP login via SMS.
`showPhoneFlag`	`boolean`	Renders country flag emojis in the phone input country code selector. When enabled, a flag emoji appears next to each country name in the dropdown and in the trigger. See Phone input below. Defaults to `false`.
`pinnedCountryCodes`	`string[]`	Array of dial codes (without `+`) pinned to the top of the phone input country dropdown, separated by a divider from the rest of the list. Only applies when `showPhoneFlag` is `true`. Defaults to `['1', '91']` (United States, Canada, and India).
`defaultPhonePrefix`	`string`	Default country dial code (without `+`) pre-selected when a phone input loads. Must match a dial code in the country list. Defaults to `'91'` (India). See Phone input below.
`showBackupCodes`	`boolean`	Enable to show Backup Code screens after MFA enrollment.
`storage`	`IStorage`	Pluggable storage backend for the SDK token cache. Defaults to an in-memory `Map` (tokens do not persist across page reloads). Pass an `IStorage` implementation to use `localStorage`, cookies, or any custom storage. The SDK exports `InMemoryStorage` as a built-in implementation.
`skipCheckSession`	`boolean`	When `true`, the SDK skips the `/ssologin/login` session check on initialization. Useful when you want to control session initialization manually. Defaults to `false`.

Option details

The following fields have nested shape, multiple modes, or interactions worth documenting in depth. Use this section as the deep reference when the one-line description in the preceding table is not enough.

successMessageConfig

Controls how success messages are displayed after form actions (e.g. registration, password reset).

Field	Type	Values	Default
`messageType`	`string`	`'toast'`, `'container'`, `'none'`	`'container'`
`duration`	`number`	Duration in milliseconds	`3200`

successMessageConfig: {
  messageType: 'container',
  duration: 5000
}

toast — displays a floating notification
container — renders the message inline within a designated container element
none — suppresses the message entirely (handle success via callbacks)

errorMessageConfig

Controls how error messages are displayed when form actions fail. Uses the same fields as successMessageConfig.

Field	Type	Values	Default
`messageType`	`string`	`'toast'`, `'container'`, `'none'`	`'toast'`
`duration`	`number`	Duration in milliseconds	`3200`

errorMessageConfig: {
  messageType: 'toast',
  duration: 4000
}

resendRestriction

Sets a cooldown timer (in seconds) on the resend button used by flows that send a one-time code or link. After the user clicks resend, the button is disabled and shows a countdown, reactivating only once the configured time has elapsed — throttling repeated send requests across all components. A flow that is not listed has no cooldown.

It is organized by delivery channel (email, sms) plus a workflow map for Identity Orchestration steps:

Key	Type	Description
`email`	`object`	Cooldown in seconds per email-based flow: `ForgotPassword`, `Registration`, `OneClickSignin`, `TwoFactorAuthentication`, `ForgotPIN`.
`sms`	`object`	Cooldown in seconds per SMS-based flow: `ForgotPassword`, `Registration`, `OneClickSignin`, `TwoFactorAuthentication`.
`workflow`	`object`	Cooldowns for workflows, keyed by workflow name, then by button ID (`smsotp`, `emailotp`, or a custom resend button's ID). Value is in seconds.

resendRestriction: {
  email: {
    ForgotPassword: 5,
    Registration: 10,
    OneClickSignin: 8,
    TwoFactorAuthentication: 3,
    ForgotPIN: 5,
  },
  sms: {
    ForgotPassword: 30,
    Registration: 45,
    OneClickSignin: 30,
    TwoFactorAuthentication: 15,
  },
  workflow: {
    loginWorkflow: {
      smsotp: 15,
      emailotp: 10,
      "<AdditionalButtonID>": 20,
    },
    signupWorkflow: {
      smsotp: 30,
    },
    "<WorkflowName>": {
      "<ButtonID>": 10,
    },
  },
}

For example, ForgotPassword: 5 disables the Forgot Password resend button for 5 seconds after each click. See Resend button cooldown for more.

formValidationMode

Controls when inline validation errors appear as users fill out SDK forms.

onBlur (default) — validation runs when the user leaves a field (on blur), including when they click outside the field or form. Error messages surface only after the user has finished interacting with each input.
onChange — validation runs as the user types, so invalid input shows an error message in real time.

formValidationMode: "onChange";

note

Submit-time validation always runs in both modes — required fields and format checks are still enforced when the form is submitted. formValidationMode only changes when inline errors appear before submission.

Phone input

The phone input country code selector supports flag emojis, pinned countries, and a configurable default prefix. These options affect every phone input field rendered by the SDK — including registration, login, profile editing, and passwordless flows.

Option	Type	Default	Description
`showPhoneFlag`	`boolean`	`false`	Renders a flag emoji next to each country name in the dropdown and in the trigger.
`pinnedCountryCodes`	`string[]`	`['1', '91']`	Dial codes (without `+`) pinned to the top of the dropdown, separated by a divider from the remaining countries.
`defaultPhonePrefix`	`string`	`'91'`	Dial code (without `+`) pre-selected when the phone input loads. Must match a dial code in the country list.

When showPhoneFlag is true, the SDK converts each country's ISO 3166-1 alpha-2 code into a flag emoji using Unicode regional indicator symbols — no images or external assets are required.

The pinnedCountryCodes array uses dial codes without the + prefix. For example, '1' covers both the United States and Canada (which share the +1 dial code), and '91' covers India. Pinned countries appear at the top of the preceding dropdown a divider line; the rest of the list follows alphabetically.

JavaScript SDK
React SDK
Auth Studio – Before Script

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>",
  showPhoneFlag: true,
  pinnedCountryCodes: ["1", "91", "44"],
  defaultPhonePrefix: "1",
});

<LoginRadiusProvider
  options={{
    apiKey: "<YOUR_API_KEY>",
    showPhoneFlag: true,
    pinnedCountryCodes: ["1", "91", "44"],
    defaultPhonePrefix: "1",
  }}
>
  <Auth />
</LoginRadiusProvider>

// Auth Studio → template editor → Pages → Auth → Before Script.
// Set the option on `commonoptions` before the SDK is created.
commonoptions.showPhoneFlag = true;
commonoptions.pinnedCountryCodes = ["1", "91", "44"];
commonoptions.defaultPhonePrefix = "1";

// Already present in the default Before Script:
var LRObject = new LoginRadiusSDK(commonoptions);

The preceding example pins the United States, Canada, India, and the United Kingdom to the top of the dropdown and defaults to the +1 prefix.

note

pinnedCountryCodes only takes effect when showPhoneFlag is true. When showPhoneFlag is false or omitted, the country selector renders without flags or pinned countries.

displayPasswordStrength

Shows a real-time password-strength checklist beside the field where a user creates a new password, so they see which requirements are still unmet before submitting. displayPasswordStrength is a configuration object, and the checklist renders only when isEnabled is true.

This is a common option: set it once in your shared SDK options and it applies automatically to every new-password field it reaches, with no per-component setup. It behaves identically in the JavaScript SDK and the React SDK.

Field	Type	Default	Description
`isEnabled`	`boolean`	`false`	Required to show the checklist.
`displayAlignment`	`'left' \| 'right'`	`'right'`	Which side of the field the checklist appears on. On screens 640px wide or narrower it always stacks below the field.
`messages`	`object`	`{}`	Per-rule text overrides for the checklist rows, keyed by rule name. See Customizing rule messages below.

displayPasswordStrength: {
  isEnabled: true,
  displayAlignment: "left",
  messages: {
    min_length: "Use {value}+ characters",
    contains_uppercase: "Add a capital letter",
  },
}

The requirements come from your application's password policy — you do not define them in the SDK. The checklist is a display aid only: validation is always enforced on submit against the same policy, so the checklist and the enforced rules never disagree.

The checklist attaches to every field where a user sets a new password — Register, Reset Password, and Change Password or Set Password — but not to the Confirm Password or Current Password fields. Each requirement flips green when met and red when unmet as the user types, and met requirements sort to the top. The checklist hides on blur. On an invalid submit, the field shows one generic message, since the red markers already show what is missing.

note

If your password policy is a custom regular expression the SDK does not recognize, the checklist is not shown and the field falls back to standard inline validation using your policy's configured message.

Customizing rule messages

Each checklist row's text can be overridden by rule key through messages. For length rules, the {value} placeholder is replaced with the length configured in your policy. Unknown keys, and empty or whitespace-only values, are ignored and fall back to the built-in text, so an override can never remove a row your policy still enforces. Only rules present in your policy produce a row.

Rule key	Default text
`min_length`	At least `{value}` characters
`max_length`	No more than `{value}` characters
`exact_length`	Exactly `{value}` characters
`numeric`	Numbers only (0-9)
`integer`	A whole number (e.g. 25 or -25)
`decimal`	A number (e.g. 25 or 25.5)
`alpha`	Letters only (A-Z, a-z)
`alpha_dash`	Only letters, numbers, dashes and underscores
`alpha_numeric`	Only letters and numbers allowed
`alphanumeric_combo`	Letters and numbers only (at least one of each)
`alpha_numeric_dash_combo`	Letters, numbers and dashes only (at least one of each)
`is_natural`	A whole number (0 or higher)
`is_natural_no_zero`	Positive numbers only
`valid_base64`	A valid Base64 string
`valid_ca_zip`	A valid postal code
`valid_ip`	A valid IP address
`valid_url`	A valid URL
`valid_credit_card`	A valid credit card number
`valid_phoneno`	A valid phone number
`contains_uppercase`	An uppercase letter (A-Z)
`contains_lowercase`	A lowercase letter (a-z)
`contains_number`	A number (0-9)
`contains_special`	A special character (@$!%*#?&)
`allowed_charset`	Only letters, numbers and @$!%*#?& allowed

The contains_* and allowed_charset rows appear only when your policy uses a recognized complexity preset such as the Admin Console's High complexity, which ships as a single advanced rule and gets decomposed into these friendly rows. Every other key maps to a standard rule and appears whenever that rule is present in your policy.

defaultFieldValues

Pre-populates sign-up and profile fields with values you choose, instead of every field starting empty. It is opt-in: list only the fields you want to default, keyed by the exact field name (case-sensitive, including the cf_ prefix on custom fields).

defaultFieldValues: {
  country: "US",                  // string field — shown pre-filled, still editable
  timezone: "America/New_York",   // hidden field — never shown, sent automatically
  cf_subscribe_to_updates: true,  // checkbox field — pre-checked
}

country is a plain string field: the form renders it already filled in with "US", and the user can still change or clear it before submitting. timezone is configured as a hidden field: it never appears on the form at all, but "America/New_York" is still submitted with the form, typically a value your app resolves from the user's locale or IP address rather than a fixed string. cf_subscribe_to_updates is a checkbox field, and the cf_ prefix marks it as a custom field: setting it to true starts the checkbox checked, and the user can still uncheck it before submitting.

A default applies wherever that field appears: on Register, including sign-up through an invitation link, on the additional-details screens shown after social or password sign-in, on any still-blank field in Personal Details. A visible field renders pre-filled and stays fully editable. A hidden field is never shown, but its value is still submitted. A field you do not configure keeps its normal empty default.

For dropdown fields, use the option's underlying value rather than its displayed label. For checkboxes, use true to start checked.

note

A value already established earlier in the session, for example an email confirmed during an availability check or tied to an invitation link, always takes priority over a configured default.

advancedFieldSingletonConfig

Advanced field groups, repeatable sections such as Addresses, Phone Numbers, Educations, and Positions, normally render as a list with an "Add another" button and a Remove control per item. advancedFieldSingletonConfig flags specific groups to render as one non-repeatable instance instead, no Add or Remove control, though the fields stay fully editable. It is opt-in, keyed by the group's exact schema name set to true.

advancedFieldSingletonConfig: {
  addresses: true,      // Addresses
  phonenumbers: true,   // Phone Numbers
  educations: false,    // Educations
  positions: false,     // Positions
  skills: false,        // Skills
  imaccounts: false,    // IM Accounts
  interests: false,     // Interests
  sports: false,        // Sports
}

Singleton mode is honored everywhere the group can be edited, on Register, on the additional-details screens, and in Profile's edit view and summary card. A flagged group shows no item number, no Add button, and no Remove or Delete control, only Edit. If the account has no data yet for that group, an empty editable instance is shown so there's still something to fill in. If the account already has more than one saved entry, only the first is shown and editable.

note

This only changes the UI's Add and Remove affordances. It does not change what your backend schema or field policy allows. The key must match the group's schema name exactly, as shown earlier, lowercase and without spaces or separators. Matching is case-sensitive, so phoneNumbers or PhoneNumbers is silently treated as false (repeatable), only the exact phonenumbers key works.

prefillWorkflowIdentifier

Carries an identifier the user typed on an earlier Identity Orchestration workflow step into the matching field on later steps of the same workflow run. A workflow that asks for the same email or phone number on several steps then presents it already filled in after the first entry.

prefillWorkflowIdentifier: true;

Matching is by the form node's type rather than its name, so a workflow that labels the node differently on each step still pre-fills. Only identifier node types are carried: email, phone, phonenumber, and username.

A non-empty value returned by the workflow API takes precedence over the carried value, so a step can still replace what the previous step captured. The carried value is held in memory for the duration of the run only. It is discarded on page reload and when a workflow restarts, and it is never written to storage.

note

Pre-fill is scoped to a single workflow run, so it applies to the Workflow component: workflow in the LoginRadius JavaScript SDK and Workflow in the LoginRadius React SDK.

disableSocialLocalization

By default, the SDK opens a social provider's login page (Google, Facebook, and others) in the browser's own language. disableSocialLocalization turns that off, so the provider's page opens in its own default language instead. It only affects social login pages. The SDK's own screens keep whatever disableLocalization and localizationConfig already control.

disableSocialLocalization: true;

note

If disableLocalization is already true, social pages are unlocalized regardless of this option.

After a provider such as Google or Facebook authenticates a user, LoginRadius returns an access token to your application. The callbackInsideSameWindow and callbackType options work together to control how that token is returned and where the user lands afterward.

callbackInsideSameWindow (boolean, default false) determines where authentication takes place:

false — Authentication opens in a popup window. Your main page stays open and receives the token in the background once the user signs in.
true — The current tab navigates to the provider and then redirects back to your callbackUrl. No popup is used.

callbackType ('' | 'hash' | 'querystring', default '') determines the mechanism used to hand the token back to your application. Its exact effect depends on the value of callbackInsideSameWindow, as shown in the following section.

Behavior reference

The following matrix shows the runtime result of every supported callbackInsideSameWindow + callbackType combination, so you can pick the pairing that matches your hosting model (static, SPA, or server-rendered) and security posture.

callbackInsideSameWindow	callbackType	Result
`true`	`''`	The token is sent to `callbackUrl` as an HTTP `POST`. Your server must handle this request; static and SPA hosts respond with `405`.
`true`	`'hash'`	The browser redirects to `callbackUrl#lr-token=<token>`. The SDK reads the token from the URL hash on load and signs the user in.
`true`	`'querystring'`	The browser redirects to `callbackUrl?lr-token=<token>`. The SDK reads the token from the query string on load and signs the user in. The page reloads in the process.
`false`	`''`	The token is passed to the main window in the background and the popup closes. The user is signed in without any change to the page URL.
`false`	`'hash'`	The token is appended to the main window's URL hash, and the SDK signs the user in as soon as the change is detected — no reload required. The popup then closes.
`false`	`'querystring'`	The token is appended to the main window's query string, which triggers a reload. The SDK detects the token during initialization on the new page and signs the user in.

How the token is detected

When the SDK initializes, it automatically checks for a pending social login token — no manual wiring is required. Depending on the configured callbackType, one of the following applies:

URL-based ('hash' or 'querystring') — The SDK inspects the URL hash first, then the query string. If a token is present, the user is signed in immediately.
Background message ('', popup flow) — The SDK listens for the token from the popup. For security, it accepts the message only from the LoginRadius domain or a configured customDomain, and validates the token before using it, so a token cannot be injected from another origin.

Examples

The following snippets show the three configurations you will reach for most often — the SPA default, a server-handled POST callback, and a same-tab redirect for static hosts.

// Standard popup (recommended for SPAs) — both values are the defaults
{
  callbackInsideSameWindow: false,
  callbackType: '',
}

// Same-window with hash (no server required)
{
  callbackInsideSameWindow: true,
  callbackType: 'hash',
  callbackUrl: 'https://yourapp.com/auth',
}

// Same-window with query string
{
  callbackInsideSameWindow: true,
  callbackType: 'querystring',
  callbackUrl: 'https://yourapp.com/auth',
}

// Popup with hash fallback
{
  callbackInsideSameWindow: false,
  callbackType: 'hash',
}

note

Using callbackType: 'querystring' triggers a full page reload. The SDK re-detects the token automatically on the new page, so no extra handling is needed, but any in-memory UI state is reset. Using callbackType: '' with callbackInsideSameWindow: true requires a server that can handle a POST request — on a static file server it returns 405 Method Not Allowed, so use 'hash' or 'querystring' during SPA development.

Validation rules

Validation rules define the constraints the SDK enforces on a form field before submission. You assign one or more rules to a field, and the SDK checks the field's value against each rule; when a rule fails, the SDK renders the matching message from mapValidationMessages (see Validation rule messages). Combine multiple rules on one field by separating them with a pipe (|), for example required|valid_email.

Rules that take a parameter use bracket notation — for example, min_length[8] requires at least eight characters, and matches[password] compares the field against another field named password. The formValidationMode option controls when these rules run relative to user input; see formValidationMode.

Rule	Parameter	Description
`required`	—	The field must not be empty.
`valid_email`	—	The value must be a well-formed email address.
`valid_username`	—	The value must be a valid username.
`valid_email_username`	—	The value must be a valid email address or a valid username.
`valid_phoneno`	—	The value must be a valid phone number.
`min_length[n]`	`n`	The value must be at least `n` characters long.
`max_length[n]`	`n`	The value must be no longer than `n` characters.
`exact_length[n]`	`n`	The value must be exactly `n` characters long.
`greater_than[n]`	`n`	The numeric value must be greater than `n`.
`less_than[n]`	`n`	The numeric value must be less than `n`.
`integer`	—	The value must be an integer.
`numeric`	—	The value must be numeric.
`decimal`	—	The value must be a decimal number.
`is_natural`	—	The value must be a natural number (`0`, `1`, `2`, and so on).
`is_natural_no_zero`	—	The value must be a natural number greater than zero.
`alpha`	—	The value must contain only alphabetic characters.
`alpha_numeric`	—	The value must contain only alphanumeric characters.
`alpha_dash`	—	The value must contain only alphanumeric characters, underscores, or dashes.
`alphanumeric_combo`	—	The value must contain a combination of letters and numbers.
`alpha_numeric_dash_combo`	—	The value must contain letters and numbers, and may include dashes.
`valid_url`	—	The value must be a well-formed URL.
`valid_ip`	—	The value must be a valid IP address.
`valid_base64`	—	The value must be a valid Base64-encoded string.
`valid_ca_zip`	—	The value must be a valid Canadian postal code.
`valid_credit_card`	—	The value must be a valid credit card number.
`callback_valid_date`	—	The value must be a valid date.
`matches[field]`	`field`	The value must match the value of the named field, such as a password confirmation.
`custom_validation`	—	Applies a custom validation function you supply for cases the built-in rules do not cover.

Usage examples

A representative end-to-end configuration combining the most common settings — credentials, theming, localization, CAPTCHA, templates, UI messaging, resend cooldowns, and validation mode:

const LRObject = new LoginRadiusSDK({
  // Core
  apiKey: "<YOUR_API_KEY>",
  verificationUrl: "https://yourdomain.com/verify",
  callbackUrl: "https://yourdomain.com/callback",
  callbackInsideSameWindow: false,
  callbackType: "hash",
  resetPasswordUrl: "https://yourdomain.com/reset-password",
  customDomain: "auth.yourdomain.com",
  apiCustomDomain: "api.yourdomain.com",
  projectionFields: ["Email", "FirstName", "LastName", "Uid"],
  isMobile: false,
  enableIdentifierCheck: true,

  // Theming
  templateName: "my-brand",
  styleName: "light-theme",

  // Localization
  disableLocalization: false,
  localizationConfig: {
    login: { buttonText: "Sign in" },
  },

  // CAPTCHA
  v2Recaptcha: true,
  captchaLanguage: "en",

  // Email templates
  verificationEmailTemplate: "verification-default",
  welcomeEmailTemplate: "welcome-v1",
  resetPasswordEmailTemplate: "reset-password-v1",
  resetPasswordConfirmationEmailTemplate: "reset-confirm-v1",
  passwordlessLoginEmailTemplate: "passwordless-email-v1",

  // SMS templates
  smsTemplate2FA: "otp-2fa",
  smsTemplatePhoneVerification: "phone-verify",
  passwordlessLoginSMSTemplate: "passwordless-sms-v1",

  // Phone input
  showPhoneFlag: true,
  pinnedCountryCodes: ["1", "91", "44"],
  defaultPhonePrefix: "1",

  // UI messaging
  successMessageConfig: { messageType: "toast", duration: 3200 },
  errorMessageConfig: { messageType: "container", duration: 5000 },

  // Resend button cooldown (seconds)
  resendRestriction: {
    email: { ForgotPassword: 5, Registration: 10 },
    sms: { ForgotPassword: 30 },
  },

  // Form validation
  formValidationMode: "onBlur",

  // Support
  contactusUrl: "https://yourdomain.com/support",
});

Action query parameter

The Auth component can read an action query parameter from the page URL to choose which screen it renders first. When action is present, it takes precedence over the Auth component's configured default screen.

For example, if Auth defaults to the login screen but the URL is ?action=register, the registration screen is shown instead.

info

The action query parameter is honored only when you initialize the Auth component. It is ignored when you initialize an individual component — such as Login, Register, or Forgot Password — directly.

Supported actions

The following values are recognized by the Auth component:

Action	Screen
`login`	Login screen (default)
`register`	Registration screen
`forgotpassword`	Forgot Password screen
`passwordless`	Passwordless Login screen
`logout`	Initiates the logout flow

Examples

Each URL below renders the corresponding screen when Auth is initialized on that page:

https://<tenant-name>.hub.loginradius.com/auth?action=register         → Registration screen
https://<tenant-name>.hub.loginradius.com/auth?action=forgotpassword   → Forgot Password screen
https://<tenant-name>.hub.loginradius.com/auth?action=passwordless     → Passwordless Login screen

Replace <tenant-name> with your LoginRadius Tenant name. The base URL (https://<tenant-name>.hub.loginradius.com/auth) defaults to the Login screen when no action is provided.

Requirements

Action query parameter support is available in both the JavaScript SDK and the React SDK, but only when the Auth component is initialized:

// Supported — the action parameter is processed
LRObject.init("auth", options); // JavaScript SDK
<Auth />; // React SDK

When an individual component is initialized directly, the SDK does not process the action query parameter, and any action specified in the URL is ignored.

Frontend SDKs overview

Compare the JavaScript and React SDKs and pick the right fit for your stack.

Set up your LoginRadius account

Retrieve the API Key and SOTT credentials the SDKs need to initialize.

Get started with the JavaScript SDK

Install, initialize, and render your first auth flow with the JavaScript SDK.

Get started with the React SDK

Wrap your app with the provider and render flows as JSX components.

Customization

Theming, messages, and resend cooldown.

Localization

Translate the SDK UI copy into any language.

Step callbacks

Track step-level progress with onStepShown, onStepSuccess, and onStepError.

Configuration

Reference

Option details

successMessageConfig

errorMessageConfig

resendRestriction

formValidationMode

Phone input

JavaScript SDK

React SDK

Auth Studio – Before Script

displayPasswordStrength

Customizing rule messages

defaultFieldValues

advancedFieldSingletonConfig

prefillWorkflowIdentifier

disableSocialLocalization

Social login callback options

Behavior reference

How the token is detected

Examples

Validation rules

Usage examples

Action query parameter

Supported actions

Examples

Requirements

Related resources