Introduction
In Liferay, the default login portlet serves the basic authentication flow but often falls short when projects demand a custom look & feel. Fragments provide a lightweight and flexible way to override or enhance the login experience without touching the core portal code. By creating a login fragment, developers can redesign the form, inject custom validations using scripts, or extend the login process while still leveraging Liferay’s built-in authentication framework. This approach keeps customization upgrade-safe and fully aligned with Liferay best practices.
Prerequisites :
Liferay DXP/Portal 7.X
Basic knowledge of Liferay
Environmental Requirements :
Liferay Portal or DXP
Ways to customize Liferay’s login using fragments :
01) Create a new site or use guest site
The first step in customizing Liferay’s login functionality out of the box is to build a new Liferay site if you want site-level login capabilities, or to use Liferay’s existing guest site.
Here we will create a new site.
Go to Control Panel > Sites > Create a new site. Give the site a name that suits your needs.
02) Add public page for sign-in
In the next stage, we’ll develop Liferay’s public page and place it at the top of the page list.
I created a page in my test site and gave it the name sign-in.
- As you can see in the image above, we need to create a blank page in our newly created site.
- Go to the page’s setup and hide it from navigation, as well as close the header and footer sections.
03) Create a fragment for sign-in implementation & design
Now we must develop a Liferay fragment to design the sign-in page and map the login functionality.
- As you can see in the image above, I have created a Sign in fragment under the blog folder.
- Now we design and customize the default Liferay’s login functionalities.
- HTML
[#if themeDisplay.isSignedIn() && !themeDisplay.getLayout().isSystem()] <script type="litespeed/javascript">window.location.replace('${themeDisplay.getPathFriendlyURLPrivateGroup() + themeDisplay.getScopeGroup().getFriendlyURL()}')</script> [@liferay_aui.script]
window.location.replace("${themeDisplay.getPathFriendlyURLPrivateGroup() +
themeDisplay.getScopeGroup().getFriendlyURL()}"); [/@] [/#if]
<div class="bg-brand-primary-darken-5 custom-sign-in vh-100">
<div class="h-100 no-gutters row">
<div class="col-lg-4 col-md-5 d-flex form-column text-neutral-0">
<div class="align-items-center d-flex flex-column justify-content-center mr-6 custom-login-form">
<a data-lfr-editable-id="home" data-lfr-editable-type="link" href="#">
<img data-lazyloaded="1" src="data:image/gif;base64,R0lGODdhAQABAPAAAMPDwwAAACwAAAAAAQABAAACAkQBADs=" decoding="async" class="ml-3 mt-6 position-absolute sign-in-logo" data-lfr-editable-id="custom-logo" data-lfr-editable-type="image" data-src="[resources:logo_inv.svg]" alt="[resources:logo inv | Customize and handle Liferay login using a fragment" title="[resources:logo inv | Customize and handle Liferay login using a fragment">
</a>
<div class="ml-lg-10 ml-md-10 ml-sm-0 w-100">
<h3 class="login-title">Sign in to Page</h3>
[@liferay_portlet.runtime portletName="com_liferay_login_web_portlet_LoginPortlet" /]
</div>
</div>
</div>
<div class="col-lg-8 col-md-7 sign-in-image"></div>
</div>
</div>
- Javascript
const EMAIL_INPUT_ID = '#_com_liferay_login_web_portlet_LoginPortlet_login';
const PASSWORD_INPUT_ID =
'#_com_liferay_login_web_portlet_LoginPortlet_password';
function inputValidation() {
const emailInput = fragmentElement.querySelector(EMAIL_INPUT_ID);
const passwordInput = fragmentElement.querySelector(PASSWORD_INPUT_ID);
if (emailInput) {
window.onload = function () {
emailInput.focus();
};
}
emailInput.focus();
const EMAIL_REGEX = /^[\w-.]+@([\w-]+\.)+[\w-]{2,4}$/g;
const TEXT_VARIANT = {
danger: 'border-danger',
success: 'border-success',
};
const isEmailValid = (email) => {
const regex = new RegExp(EMAIL_REGEX);
return regex.test(email);
};
function onInputChange(element, validation) {
if (validation) {
element.classList.remove(TEXT_VARIANT.danger);
element.classList.add(TEXT_VARIANT.success);
return;
}
element.classList.remove(TEXT_VARIANT.success);
element.classList.add(TEXT_VARIANT.danger);
}
emailInput.addEventListener('change', () =>
onInputChange(emailInput, isEmailValid(emailInput.value))
);
passwordInput.addEventListener('change', () =>
onInputChange(passwordInput, passwordInput.value !== '')
);
}
inputValidation();
As you can see in the code above, I have designed a login fragment as per my requirement.
You can design with CSS and JS as per your requirement.
I’ve added functionality that allows users to see the login element while they’re signed in, but not when they’re not.
You can also add new HTML tags and CSS to add extra functionality.
04) Put fragment on the page
Now, open the page editor for the sign in page and place the sign in fragment on it.
on the page.
Publish the sign in page and hit the page URL in the incognito window.
For me the URL is “http://localhost:8080/web/test-1/sign-in”
As shown in the image above, this is my custom login page design, which allows you to simply log in to the Liferay portal.
Conclusion
Customizing the login experience in Liferay with fragments gives you the perfect balance between flexibility and maintainability. Instead of overriding core components, you can tailor the design, add validations, and enhance usability—all while keeping the solution upgrade-safe. Whether it’s aligning the login page with your branding or introducing custom logic, fragments make the process simple and effective. With this approach, you not only improve the user experience but also maintain clean, modular, and future-ready portal development.
