Custom Flows
Learn the process behind building custom sign-up and sign-in flows with Clerk.
Overview
If our Prebuilt Components don't meet your specific needs or you require more control over the authentication flow, Clerk enables you to build fully custom sign-up and sign-in flows using our useSignUp() and useSignIn() React hooks.
But before diving in deep to the code side, it is important to first understand the process behind building sign-up and sign-in flows, which fields are required fields, and the necessary steps to authenticate a user.
Sign-up flow
Clerk provides a flexible way to build sign up flows in your application. You can use a single Sign Up object to gather information, verify their email address or phone number, add OAuth accounts, and finally, convert them into a User.
Every Sign Up 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 dashboard. Once all requirements are met, the Sign Up 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 Sign Up will show the current state of requirement collection. 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 |
|---|---|
| required_fields | All fields that must be collected before the Sign Up converts into a User. |
| optional_fields | All fields that can be collected, but are not necessary to convert the Sign Up. |
| missing_fields |
A subset of required_fields. It contains all fields that still need to be
collected before a
successful Sign Up. Note that the missing_fields will be updated dynamically. As you add
more fields to the Sign Up, they will be removed from missing_fields. Once it's
empty, your
Sign Up will automatically convert into a User.
|
The values of the collected fields are all accessible on the root of the Sign Up, under their corresponding keys; email_address and phone_number are examples of such keys.
Verified fields
Some fields, such as email_address and phone_number , must be verified before it is fully added to the Sign Up. Similar to what happens with required fields, the Sign Up contains the current state of all verified fields. The keys relative to verification are unverified_fields and verifications.
| Name | Description |
|---|---|
| unverified_fields | a list of all User. attributes that need to be verified and are pending verification. This is a list that gets updated dynamically, eventually becoming an empty array, when verification for all required fields has been successfully completed. |
| verifications |
an object that describes the current state of verification for the
Sign Up.. There are currently three different keys nested in there;
email_address, phone_number and external_account.
|
Sign-in flow
Sign in's are initiated by creating a Sign in object on the current Client. The Sign in 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:
Step 1: 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.
Step 2: Factor one verification
Once a user is identified, they need to prove that "they are who they say they are". This is the process of "authenticating" the user. There's a number of strategies a user can use to perform authentication, the most basic being the humble password. Other authentication strategies that Clerk provides, are sending an email_code or phone_code. This will send an email or an SMS message with a code, that the user then must provide in order to sign in.
Step 3: Factor two verification (optional)
This step only applies to users that have turned on two factor authentication for their user. When one form of verification isn't enough, trust two! But seriously. 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.