Create a Custom Login Form

What You’ll Need (Form Setup)

Before adding any code, your custom login form must include at least these two fields:

These names (username, password) will be referenced in the PHP script, so they have to match exactly.

PHP Logic for Authentication & Login

Once your fields are in place, go to PHP Scripts → Form Process area in Convert Forms to paste the login logic. 

// The field representing the username
$username = $post['username'];

// The field representing the password
$password = $post['password'];

// The message that will appear when both fields are not filled
$fill_fields = 'Please enter a username and password';

// The message that will appear when a user does not exist given its username
$user_does_not_exist = 'User does not exist';

// The message that will appear when an invalid password is given.
$invalid_password = 'Invalid password';

// Message that appears when Joomla cannot validate the user
$login_failed = 'Login Failed';

// Do not edit below
if (empty($username) || empty($password))
{
    throw new Exception($fill_fields);
}

$query = $db->getQuery(true)
	->select('id, password')
	->from('#__users')
	->where('username=' . $db->quote($username));

$db->setQuery($query);

if (!$result = $db->loadObject())
{
    throw new Exception($user_does_not_exist);
}

// Validate login credentials
if (\Joomla\CMS\User\UserHelper::verifyPassword($password, $result->password, $result->id))
{
    $credentials = [
		'username' => $username,
    	'password' => $password
	];

    //perform log in
    $response = $app->login($credentials);

    if (!$response)
	{
		throw new Exception($login_failed);
	}
}
else
{
    throw new Exception($invalid_password);
}

Here’s a breakdown:

• First, the script checks whether both username and password fields are filled.
• It queries the Joomla #__users table to fetch that user’s stored password hash.
• It uses UserHelper::verifyPassword() to validate the provided password.
• If the validation passes, it calls $app->login() to perform the actual login.
• Any failure (empty fields, no user, invalid password, login failure) throws an exception with your custom message.

Redirecting After Login

Once login succeeds, you’ll usually want to send the user to a particular page. In Convert Forms:

1. Go to Submission → Successful Submission Action
2. Choose Redirect user
3. Enter the URL to which you want users redirected

That way, after successful login, they’ll end up where you want (dashboard, profile page, etc.).

Displaying a Logout Link

When a user is logged in, it doesn’t make sense to keep showing the login form. You can override the form display via PHP to show a “Logout” link instead. Use the PHP Scripts → Form Display area, with something like:

$user = \Joomla\CMS\Factory::getUser();
if ($user->id) {
	$userToken = \Joomla\CMS\Session\Session::getFormToken();
	$formLayout = '<a href="' . \Joomla\CMS\Router\Route::_('index.php?option=com_users&task=user.logout&' . $userToken . '=1') . '">Logout</a>';
}

This checks if you’re already logged in ($user->id is nonzero) and outputs a logout link using Joomla’s routing and session token for security.

Avoiding Storing Passwords in the Database

Since the form submission may log all submitted fields, including the password, you should prevent that field from being stored. You can configure Convert Forms not to save a field by using a really small PHP snippet that can be found here.

Want to Create a Custom Registration Form Too?

If you enjoyed building a custom login form, you’ll probably want to customize your registration process as well.

In another step-by-step guide, we show you how to create custom registration forms in Joomla using Convert Forms. You’ll learn how to design a beautiful registration experience, map user data, add custom fields, and even trigger automation after signup.

By combining both tutorials, you can take full control of your Joomla user flow, from registration to login, all with your own forms.