Custom flows
If Clerk's prebuilt components don't meet your specific needs or if you require more control over the authentication flow, Clerk enables you to build fully custom sign-up and sign-in flows using the useSignUp() and useSignIn() React hooks.
Sign-up flow
Clerk provides a flexible way to build sign-up flows in your application. You can use a single SignUp object to gather information, verify their email address or phone number, add OAuth accounts, and finally, convert them into a User.
Every SignUp has a set of requirements it must meet before it is turned into a User. These requirements are defined by the instance settings you selected in the Clerk Dashboard(opens in a new tab). Once all requirements are met, the SignUp will turn into a new User, and an active session for that User will be created on the current Client.
Don't worry about collecting all the required fields at once and passing them to a single request. The API is designed to accommodate a progressive sign-up flow, often corresponding to multi-step sign-up forms.
Required fields
The SignUp object will show the state of the current sign-up. You can consult the required_fields, optional_fields, and missing_fields keys for a hint on where things are and what you need to do next.
| Name | Description |
|---|---|
requiredFields | All fields that must be collected before the SignUp converts into a User. |
optionalFields | All fields that can be collected, but are not necessary to convert the SignUp. |
missing_fields | A subset of required_fields. It contains all fields that still need to be collected before a successful SignUp. Note that the missingFields will be updated dynamically. As you add more fields to the SignUp, they will be removed from missing_fields. Once it's empty, your SignUp will automatically convert into a User. |
The values of the collected fields are all accessible on the root of the SignUp, under their corresponding keys; email_address and phone_number are examples of such keys. Go to the SignUp object documentiation for a list of all available attributes.
Verified fields
Some fields, such as email_address and phone_number, must be verified before they are fully added to the SignUp. Similar to what happens with required fields, the SignUp contains the current state of all verified fields. The keys relative to verification are unverified_fields and verifications.
| Name | Description |
|---|---|
unverifiedFields | A list of all User attributes that need to be verified and are pending verification. This is a list that gets updated dynamically. When verification for all required fields has been successfully completed, this value will become an empty array. |
verifications | An object that describes the current state of verification for the SignUp. There are currently three different keys: email_address, phone_number, and external_account. |
Sign-in flow
Sign-in's are initiated by creating a SignIn object on the current Client. The SignIn handles all the state and logic associated with a sign-in. If the sign-in is successfully authenticated, it will transform into an active session on the current Client.
Completing a sign-in
There are 3 main steps a user must perform in order to complete a sign-in.
Identification
The first step a user needs to make is to identify what account they'd like to sign in to. This is done with an identifier, which can either be an email address, a phone number, or a username.
Factor one verification
Once a user is identified, they need to prove their identity. This is the process of "authenticating" the user. There's a number of strategies a user can use to perform authentication with the most basic being the humble password. Other authentication strategies, like passwordless sign-in, can be explored in the sign-in options documentation.
Factor two verification (optional)
This step only applies to users that have turned on two-factor authentication, also known as multifactor authentication, for their user.
When one form of verification isn't enough, trust two! Forcing two different verification steps vastly increases the security of your account. The most common setup a user will have to protect their account is using a password as their first kind of verification and a phone_code as their second kind of verification.