useSignUp() and useSignIn()

Overview

If our Prebuilt Components don't meet your needs, you can build a fully custom sign-up or sign-in flow using the React hooks useSignUp() and useSignIn() respectively.

The useSignUp() hook gives you access to the SignUp object and its available methods in order to build a custom sign-up flow. The SignUp object will also contain the state of the sign-up attempt that is currently in progress, which gives you the ability to examine all the details and act accordingly.

Usage

Getting access to the SignUp object from inside one of your components is easy. Note that the useSignUp() hook can only be used inside a <ClerkProvider/> context.

The following example accesses the SignUp object to check the current sign-up attempt's status.

1
import { useSignUp } from '@clerk/nextjs';
2

3
export default function SignUpStep() {
4
  const { isLoaded, signUp } = useSignUp();
5

6
  if (!isLoaded) {
7
    // Handle loading state
8
    return null;
9
  }
10
  
11
  return (
12
    <div>
13
      The current sign up attempt status 
14
      is {signUp.status}.
15
    </div>
16
  );
17
}

In a more involved example, we show an approach to create a custom form for registering users, in this case with a Password strategy. This assumes that you don't have any additional requirements like username or phone enabled

1
import { useState } from "react";
2
import { useSignUp } from "@clerk/nextjs";
3
import { useRouter } from "next/router";
4

5
export default function SignUpForm() {
6
  const { isLoaded, signUp, setActive } = useSignUp();
7
  const [emailAddress, setEmailAddress] = useState("");
8
  const [password, setPassword] = useState("");
9
  const [pendingVerification, setPendingVerification] = useState(false);
10
  const [code, setCode] = useState("");
11
  const router = useRouter();
12
  // start the sign up process.
13
  const handleSubmit = async (e) => {
14
    e.preventDefault();
15
    if (!isLoaded) {
16
      return;
17
    }
18

19
    try {
20
      await signUp.create({
21
        emailAddress,
22
        password,
23
      });
24

25
      // send the email.
26
      await signUp.prepareEmailAddressVerification({ strategy: "email_code" });
27

28
      // change the UI to our pending section.
29
      setPendingVerification(true);
30
    } catch (err: any) {
31
      console.error(JSON.stringify(err, null, 2));
32
    }
33
  };
34

35
  // This verifies the user using email code that is delivered.
36
  const onPressVerify = async (e) => {
37
    e.preventDefault();
38
    if (!isLoaded) {
39
      return;
40
    }
41

42
    try {
43
      const completeSignUp = await signUp.attemptEmailAddressVerification({
44
        code,
45
      });
46
      if (completeSignUp.status !== "complete") {
47
        /*  investigate the response, to see if there was an error
48
         or if the user needs to complete more steps.*/
49
        console.log(JSON.stringify(completeSignUp, null, 2));
50
      }
51
      if (completeSignUp.status === "complete") {
52
        await setActive({ session: completeSignUp.createdSessionId })
53
        router.push("/");
54
      }
55
    } catch (err: any) {
56
      console.error(JSON.stringify(err, null, 2));
57
    }
58
  };
59

60
  return (
61
    <div>
62
      {!pendingVerification && (
63
        <form>
64
          <div>
65
            <label htmlFor="email">Email</label>
66
            <input onChange={(e) => setEmailAddress(e.target.value)} id="email" name="email" type="email" />
67
          </div>
68
          <div>
69
            <label htmlFor="password">Password</label>
70
            <input onChange={(e) => setPassword(e.target.value)} id="password" name="password" type="password" />
71
          </div>
72
          <button onClick={handleSubmit}>Sign up</button>
73
        </form>
74
      )}
75
      {pendingVerification && (
76
        <div>
77
          <form>
78
            <input
79
              value={code}
80
              placeholder="Code..."
81
              onChange={(e) => setCode(e.target.value)}
82
            />
83
            <button onClick={onPressVerify}>
84
              Verify Email
85
            </button>
86
          </form>
87
        </div>
88
      )}
89
    </div>
90
  );
91
}

The useSignIn() hook gives you access to the SignIn object and its available methods in order to build a custom sign-in flow. The SignIn object will also contain the state of the sign-in attempt that is currently in progress, which gives you the ability to example all the details and act accordingly.

Usage

Getting access to the SignIn object from inside one of your components is easy. Note that the useSignIn() hook can only be used inside a <ClerkProvider/> context.

The following example accesses the SignIn object to check the current sign-in attempt's status.

import { useSignIn } from '@clerk/nextjs';

export default function SignInStep() {
  const { isLoaded, signIn } = useSignIn();
  
  if (!isLoaded) {
    // Handle loading state
    return null;
  }
  
  return (
    <div>
      The current sign in attempt status 
      is {signIn.status}.
    </div>
  );
}

In a more involved example, we show an approach to create a custom form for signing in users, in this case with a Password strategy.

1
import { useState } from "react";
2
import { useSignIn } from "@clerk/nextjs";
3
import { useRouter } from "next/router";
4

5
export default function SignInForm() {
6
  const { isLoaded, signIn, setActive } = useSignIn();
7
  const [emailAddress, setEmailAddress] = useState("");
8
  const [password, setPassword] = useState("");
9
  const router = useRouter();
10
  // start the sign In process.
11
  const handleSubmit = async (e) => {
12
    e.preventDefault();
13
    if (!isLoaded) {
14
      return;
15
    }
16

17
    try {
18
      const result = await signIn.create({
19
        identifier: emailAddress,
20
        password,
21
      });
22

23
      if (result.status === "complete") {
24
        console.log(result);
25
        await setActive({ session: result.createdSessionId });
26
        router.push("/")
27
      }
28
      else {
29
        /*Investigate why the login hasn't completed */
30
        console.log(result);
31
      }
32

33
    } catch (err: any) {
34
      console.error("error", err.errors[0].longMessage)
35
    }
36
  };
37

38
  return (
39
    <div>
40
      <form>
41
        <div>
42
          <label htmlFor="email">Email</label>
43
          <input onChange={(e) => setEmailAddress(e.target.value)} id="email" name="email" type="email" />
44
        </div>
45
        <div>
46
          <label htmlFor="password">Password</label>
47
          <input onChange={(e) => setPassword(e.target.value)} id="password" name="password" type="password" />
48
        </div>
49
        <button onClick={handleSubmit}>Sign In</button>
50
      </form>
51
    </div>
52
  );
53
}