Last Updated: Oct 2, 2024
Overview
This document clarifies how the Universal Login page can be customized and provides guidance on when to use specific techniques.
Applies To
- Universal Login
- Customizations
Solution
Customization
A custom domain must be enabled for Universal Login page customizations to work. This is one major difference between New and Classic Universal Login.
Three mechanisms are available to customize the Universal Login page.
No-Code Editor: Style the login widget in the Universal Login experience. Personalize the color, font, borders, and backgrounds of the widgets end users see for login, password reset, authentication, and more.
Partials: Allows the injection of custom HTML or JS at specific points in the login widget.
Page Templates: Provide for customizing the layout and appearance of the login page using liquid syntax and page template variables. Cascading Style Sheets (CSS) or Javascript (JS) can be used for more extensive customization. (Examples)
Text Prompts: Allow customization of the actual text on the login page. This includes text field names and the text that renders on buttons.
Use the No-Code Editor to make basic changes to the login widget, including color, font, borders, and backgrounds.
Use Partials to add custom content to login and signup pages or to collect and validate additional data during login or signup.
Use Page Templates to make advanced changes to the layout of the page or implement conditional formatting. Page templates can use CSS or JS to hide certain page elements, as needed.
Use Text Prompts to customize the text displayed on the login page.
Customization
A custom domain must be enabled for Universal Login page customizations to work. This is one major difference between New and Classic Universal Login.
Three mechanisms are available to customize the Universal Login page.
No-Code Editor: Style the login widget in the Universal Login experience. Personalize the color, font, borders, and backgrounds of the widgets end users see for login, password reset, authentication, and more.
Partials: Allows the injection of custom HTML or JS at specific points in the login widget.
Page Templates: Provide for customizing the layout and appearance of the login page using liquid syntax and page template variables. Cascading Style Sheets (CSS) or Javascript (JS) can be used for more extensive customization. (Examples)
Text Prompts: Allow customization of the actual text on the login page. This includes text field names and the text that renders on buttons.
Use the No-Code Editor to make basic changes to the login widget, including color, font, borders, and backgrounds.
Use Partials to add custom content to login and signup pages or to collect and validate additional data during login or signup.
Use Page Templates to make advanced changes to the layout of the page or implement conditional formatting. Page templates can use CSS or JS to hide certain page elements, as needed.
Use Text Prompts to customize the text displayed on the login page.
Custom Content and Data Capture (Partials)
It is possible to upload custom HTML and JS code, called Partials, to be displayed in specific sections of the Universal Login widget. Partials can only be updated via the Partials API.
Partials can be used to do things like add a terms and conditions checkbox that must be checked before the user can complete signup. Partials support client side validation (through Javascript directly on the page) and client side validation (through actions).
Review the documentation for Customizing Signup and Login Prompts.
Page Templates
Page Templates for Universal Login can only be updated via the Page Templates API. Page templates are used to format the HTML page within which the login widget renders. For example, adding a background or controlling where on the page the widget renders.
CSS Customization
CSS can be used to make minor modifications to the login page, such as adding an in-line style sheet or a link to an external stylesheet in the page template.
Note that the CSS class names are not static, and customizations targeting them will fail. Class names change when the Auth0 product is updated, which is often. Customizations may work briefly but will fail without notice.
JS customization
JS customizations should be avoided if possible–Partials (covered earlier in this document) are easier to implement and will not be affected by changes to the Universal Login DOM.
Universal Login does not depend on JS. It contains some JS, but the page’s essential functions do not require it. JS script tags can be added to the page template to manipulate page elements. For example, to hide the signup link, consider the following template. Note this introduces a dependency on JS for the page to render as intended. JS customizations also depend on a rigid DOM structure and may break without warning (this is uncommon but has happened). Put another way, we have had generally good success with this method but JS customizations of the login widget are unsupported.
<!DOCTYPE html>
<html>
<head>
{%- auth0:head -%}
</head>
<body class="_widget-auto-layout">
{%- auth0:widget -%}
<script type="text/javascript">
document.addEventListener("DOMContentLoaded", function (event) {
Element.prototype.remove = function () {
this.parentElement.removeChild(this);
}
NodeList.prototype.remove = HTMLCollection.prototype.remove = function () {
for (var i = this.length - 1; i >= 0; i--) {
if (this[i] && this[i].parentElement) {
this[i].parentElement.removeChild(this[i]);
}
}
}
var xpath = "//a[contains(@href,'signup')]";
var signUpLink = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
if (signUpLink) {
signUpLink.parentElement.remove();
}
});
</script>
</body>
</html>
Text Prompts
Prompts can be changed on the Auth0 dashboard under Branding > Universal Login > Advanced Options > Custom Text
A “prompt” is a specific step in the login flow. For example, MFA OTP enrollment (mfa-otp) or sign-in with a username and password (login-password). A “screen” is a subset of a prompt. A prompt might have a single screen or multiple screens. The login-password prompt only has a single screen (login-password), whereas the mfa-otp prompt has the mfa-otp-enrollment-qr screen and the mfa-otp-enrollment-code screen. The former is the screen for enrolling in MFA OTP with a QR code, and the latter provides a code for the user to manually enter in their authenticator app.
The list of prompts is available at Customize Login Text Prompts.
Updating Text Prompts via API (advanced use case)
In addition to the dashboard prompt editor, prompts can be updated via the API. The syntax is:
PUT https://tenant.auth0.com/api/v2/prompts/<prompt>/custom-text/<language>
{
"<screen>": {
"<text_id>": "text1 in language"
}
}
Where:
<prompt>= a prompt from the list of prompts above<language>= a language from the list of supported languages<screen>= a screen from the prompt<text_id>= the Key from the screen.
For example, to change the Trouble Scanning? text on the MFA OTP QR code enrollment prompt for users with their language set to English, send the following payload:
PUT https://tenant.auth0.com/api/v2/prompts/mfa-otp/custom-text/en
{
"mfa-otp-enrollment-qr": {
"codeEnrollmentText": "Click here if you cleaned your camera lens and still have trouble scanning."
}
}