Skip to main content
Version: 4.xx.xxSource Code

useLogin

caution

This hook can only be used if authProvider is provided.

useLogin calls login method from authProvider under the hood.

It returns the result of react-query's useMutation which includes many properties, some of which being isSuccess and isError.

Data that is resolved from login will be returned as the data in the query result with the following type:

type AuthActionResponse = {
success: boolean;
redirectTo?: string;
error?: Error;
[key: string]: unknown;
};
  • success: A boolean indicating whether the operation was successful. If success is false, a notification will be shown.
    • If error is provided, the notification will contain the error message and name. Otherwise, a generic error message will be shown with the following values: { name: "Login Error", message: "Invalid credentials" }.
  • redirectTo: If it has a value, the app will be redirected to the given URL.
  • error: If it has a value, a notification will be shown with the error message and name.
  • [key: string]: Any additional data you wish to include in the response, keyed by a string identifier.

Usage​

refine provides a default login page which handles the login flow manually.

If you want to use a custom login page however, you can use the useLogin hook like this:

pages/customLoginPage
import { useLogin } from "@refinedev/core";
import { Form } from "antd";

type LoginVariables = {
username: string;
password: string;
};

export const LoginPage = () => {
const { mutate: login } = useLogin<LoginVariables>();

const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
e.preventDefault();

const values = {
username: e.currentTarget.username.value,
password: e.currentTarget.password.value,
};

login(values);
};

return <Form onFinish={onSubmit}>// rest of the login form</Form>;
};
tip

mutate acquired from useLogin can accept any kind of object for values since login method from authProvider doesn't have a restriction on its parameters. A type parameter for the values can be provided to useLogin.

const { mutate: login } = useLogin<{ username: string; password: string }>();

Redirection after login​

A custom URL can be given to mutate the function from the useLogin hook if you want to redirect yourself to a certain URL.

import { useLogin } from "@refinedev/core";

const { mutate: login } = useLogin();

login({ redirectPath: "/custom-url" });

Then, you can handle this URL in your login method of the authProvider.

import type { AuthBindings } from "@refinedev/core";

const authProvider: AuthBindings = {
// ---
login: async ({ redirectPath }) => {
// ---
return {
success: true,
redirectTo: redirectPath,
};
},
};

Error handling​

Since the methods of authProvider always return a resolved promise, you can handle errors by using the success value in the response:

import { useLogin } from "@refinedev/core";

const { mutate: login } = useLogin();

login(
{
email: "refine@example.com",
password: "refine",
},
{
onSuccess: (data) => {
if (!data.success) {
// handle error
}

// handle success
},
},
);
caution

The onError callback of the useLogin hook will not be called if success is false. This is because the authProvider methods always return a resolved promise, and the callback is only triggered when the promise is rejected.