Changelog May 26, 2023

As part of your onboarding flow, you may want to collect extra information from your user and use it to drive your application state. Let’s walk through a quick example using Next.js and TypeScript to show you how simple implementing an onboarding flow can be. 

Configure your middleware to read session data

Update  with the user’s onboarding state

Session tokens are JWTs that are generated by Clerk on behalf of your instance, and contain claims that allow you to store data about a user’s session. With Clerk, when a session token exists for a user, it indicates that the user is authenticated, and the associated claims can be retrieved at any time. [

 in your Clerk Dashboard and click the ‘Edit’ button. In the modal that opens, there will be a window where you can augment your session token with custom claims.

In there, add the following and hit save:

If you haven’t already, we can make the public metadata type information accessible to our application by adding the following to 

We have just added custom data to our session token in the Clerk Dashboard and made those claims accessible to our app. Next, we’ll use 

Configure your Next.js middleware to read session data

 allows you ton configure access to your routes with fine grained control. You can also retrieve claims directly from the session and redirect your user accordingly. [

 and add the following code to the file. This logic could go in the Middleware, but by adding to the 

 to the route the logic remains in one place. This file can also be expanded to handle multiple steps, if multiple steps are required for an onboarding flow.

Now that we have the logic for where to direct the user, we’ll need a way to track their onboarding status and note it on their session, let’s dig into that now!

Update publicMetadata based on onboarding state

 as they progress through the flow will allow us to recognize when they have successfully completed their onboarding and, per the logic above, are now able to access the application. [

A method in your backend to securely update the user 

A process in your frontend with logic to collect and submit all the information for onboarding. In this guide you’ll use an example form.

First, add a method in your backend, that will be called on form submission and update the user’s 

 accordingly. The example below uses the 

 wrapper to interact with the Backend API.

Now that we have a method to securely update our user’s 

 we can call this server action from a client side form.

With the backend updateUser method in place, we’ll add a basic page that contains a form to complete the onboarding process.

This example form that will capture an application name (applicationName) and application type of either B2C or B2B (applicationType). This is a very loose example — you can use this step to capture information from the user, sync user data to your database, have the user sign up to a course or subscription, or more.

To implement this logic, insert the following into your 

Your onboarding flow is now complete! 🎉 New users who haven’t yet onboarded will now land on your 

 page and, once they have completed onboarding, will be sent through to the dashboard. By using Clerk, which already handles user authentication, we were able to simplify the process of creating a custom user onboarding flow as well.

How to Add an Onboarding Flow for your Application with Clerk

Welcome to the second part of building a custom user menu! 

using the Radix Dropdown primitive and some of Clerk’s hooks. Now we’ll be upgrading our user button with sign-in functionality when the user is not logged in as well as improve the behavior of the component in several ways.

The first step is to refactor the component so it's ready to build upon. Take the contents of the 

 and create a new component in the file above the exported component. Call the new component 

 and paste the copied code. We will need to add in the destructures for the user method from the 

The first step is to refactor the component so it's ready to build upon.

Create a new component in the file called 

 component, we’re going to leave the check for 

 and add a [user.id](http://user.id) check using 

 component from Clerk if there is no user.

If you saved your work and tested it, you will see that the refactoring has already accomplished the base goal — it is now both a Sign-In button and a User Button/User Menu. We can still improve the component and provide a better user experience, so let’s do a few more refactors.

The first step is moving the button to its component. We’ll also add in a 

The second step is to refactor part of the 

> component. We want to take advantage of the new 

The third step is to refactor the top-level 

component to also use the new <Button /> component. This button will use 

 to programmatically open the sign-in modal. This results in a custom button and removal of the Clerk 

You can see that we left the user profile image inside of 

 as a child. Depending on your need you could hoist the image handling into the 

 — that’s totally up to the needs of what you’re building.

Everything is working nicely at this point, and the structure is in a great place to build on. That said, we can add a few refinements to elevate the user experience. Let’s start by installing an icon package and the class-variance-authority package.

With that installed, let’s do another refactor of the Button. We’ll use 

 to expand on what the button can do. This is a very structured approach and provides TypeScript support. We will set up a 

Now that our <Button />has reached its final form, let’s import some icons.

Let’s modify the button that serves as the trigger for the User Menu. We’ll use Clerk’s 

 we just imported when the user hasn’t set a profile image, but use their image when they have. We will also will move the logic we have for the label for the button up.

 to add a little flare to the Sign-In button.

 to add icons to the drop-down menu. At the same time we will add the variant and size to the buttons so they are using the new configuration.

We can add a few finishing touches to the component to flesh it out some more with a few smaller tweaks and improvements:

 variant, and then use that for the user button.

 to the sign-in and user button to help give them a more consistent width.

 class to remove the focus ring from the menu items

Explore the Powerful Customization Options Clerk Offers!

With this component you have the building blocks to build out your own user button and menu. Add the new entries to the dropdown that you need for your application, and use the tools provided by Radix and `cva` to design and style your component so it matches your application's design language!

 documentation to explore more ways to customize your application using the many hooks and methods Clerks provides. The ability to add the pieces you need from Clerk to fully custom and unique UI provides flexibility to projects.

For more in-depth technical inquiries or to engage with our community, feel free to 

. Stay in the loop with the latest Clerk features, enhancements, and sneak peeks by following our Twitter/X account, 

. Your journey to seamless user management starts here!

Need help?

Company

Company

Changelog May 26, 2023

Start now,
no strings attached

Pricing built for
businesses of all sizes.

Newsletter!

Company

Company

Changelog May 26, 2023

Start now,no strings attached

Pricing built for.css-qa8l2m{color:var(--chakra-colors-primary-500);}businesses of all sizes.

Newsletter!

Start now,
no strings attached

Pricing built for
businesses of all sizes.