āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/guides/development/custom-flows/overview ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
A custom flow refers to a user flow created entirely from scratch using the Clerk API. If prebuilt components don't meet your specific needs or if you require more control over the logic, you can rebuild the existing Clerk flows using the Clerk API.
[!TIP] The information in this guide will help you get a general understanding of custom flow concepts. To skip to code examples, choose the guide that best fits your needs from the navigation on the left.
Before building custom authentication flows, read the following sections to get a general understanding of how authentication flows work in Clerk.
The SignUp object is the pivotal concept in the sign-up process. It is used to gather the user's information, verify their email address or phone number, add OAuth accounts, and finally, convert them into a User.
Every SignUp must meet specific requirements before being converted into a User. These requirements are defined by the instance settings you selected in the Clerk Dashboard. For example, on the User & authentication page, you can configure email and password, email links, or SMS OTP as authentication strategies.
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 progressive multi-step sign-up forms.
The following steps outline the sign-up process:
create() method.SignIn.createdSessionId to the setActive() method on the Clerk object.navigate parameter in setActive() to access Session.currentTask and check for pending session tasks.SignUpThe SignUp object will show the state of the current sign-up in the status property.
If you need further help on where things are and what you need to do next, you can also consult the required_fields, optional_fields, and missingFields properties.
All fields that must be collected before the SignUp converts into a User.
optionalFieldsAll fields that can be collected, but are not necessary to convert the SignUp into a User.
missingFieldsA subset of requiredFields. It contains all fields that still need to be collected before a SignUp can be converted into a User. Note that this property will be updated dynamically. As you add more fields to the SignUp, they will be removed. Once this property is empty, your SignUp will automatically convert into a User.
</Properties>
Some properties of the SignUp, such as emailAddress and phoneNumber, must be verified before they are fully added to the SignUp object.
The SignUp object will show the state of verification in the following properties:
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.
verificationsAn object that describes the current state of verification for the SignUp. There are currently three different keys: email_address, phone_number, and external_account.
</Properties>
The SignIn object is the pivotal concept in the sign-in process.
Sign-ins are initiated by creating a SignIn object on the current Client. If the sign-in is successfully authenticated, it will transform into an active session for that User on the current Client.
The following steps outline the sign-in process:
create() method.SignIn.createdSessionId to the setActive() method on the Clerk object.navigate parameter in setActive() to access Session.currentTask and check for pending session tasks.Session tasks require users to complete specific actions after authentication, such as selecting an organization. These tasks ensure that users meet all requirements before gaining full access to your application.
For detailed information about configuring and implementing session tasks, see the dedicated guide.
After completing the sign-up or sign-in process, you should check if the user has any pending tasks:
navigate parameter in setActive() to access Session.currentTask and check for pending session tasks.active and the user can access protected content.You can build your own UI to handle specific task types. For example, if the task is choose-organization, you can create a custom organization creation component to allow users to create or select an organization before proceeding.
<If sdk={["nextjs"]}>
When auth.protect() detects a pending session, it redirects to /tasks under the sign-in page. Create this page to handle the pending task and redirect the user appropriately.
'use client'
import { RedirectToTasks } from '@clerk/nextjs'
export default function Page() {
return <RedirectToTasks />
}
Now that you have a general understanding of how authentication flows work in Clerk, you can start building your custom flows. To get started, choose the guide that best fits your needs from the navigation on the left.
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā