Changelog May 26, 2023

Clerk’s components were created with you in mind. Components do most of the functional work for you, allowing you to get your auth flows working in minutes, and support customization to fit your app’s style. That said, sometimes a component like the 

 doesn’t suit the needs of your application. The good news? Clerk provides hooks and functions that make building your custom UI components easy. Let’s take a quick look at how to create your custom user menu.

The hardest part of building a custom user menu is often the dropdown menu itself. You need the button to trigger the menu opening, a way to close it, a way to track open/closed states, a way to handle ‘click off’ to close, logic to close if the user hits the 

 button, a way to handle keyboard input, and the list goes on. We’re going to save ourselves some time and use a great library while doing so. Radix provides world-class, accessible, unstyled 

 that you can use to quickly and efficiently build your UI. Let’s start by installing the primitive we need — the dropdown menu.

Once the installation finishes, let’s create the scaffolding for our new component. The following will be the foundation of the menu. The trigger will hold the User button that will open the menu, and each item will hold one of the menu entries. Remember that Radix Primitives are unstyled and there is no content so this will be blank.

The first content we will add is the User button. This will show that the user is logged in, and will be the trigger to open the menu. For the sake of this post we will assume that you have marked email as required in the Clerk Dashboard, in the 

User & Authentication → Email, Password, Username → Email

 section to ensure every user has an email. You could change this to a first name or username easily enough. Just make sure that whatever option you choose is something that will exist for all users, for the sake of rendering. You could also conditionally render different information depending on what the user has provided — show the first name if available; if not, show the email.

To build the button we will leverage the 

 hook. This gives us access to information about the user, such as profile image, email, name, and more. We will also make sure that Clerk and the user have loaded, and that there is valid user data, before rendering the User button.

Add the Sign-Out and Manage Account Buttons

With the User button in place, we can now add Sign Out and Manage Account buttons. The 

 hook provides the two methods we will need for this — the 

 method. The User Profile will open as a modal. You could, instead, mount the 

 component to its own route, and then link it to the route. For the Sign Out button, we will also need to use the Next.js router to handle the redirect.

The custom button has now replicated the behavior of the 

, though it is very much still unstyled. We’re going to do one more thing — add one more menu entry to mimic expanding the menu. This will use the 

 component from Next.js to link to a fictional 

Your new component is almost ready — it just needs some styling. Let’s add a little bit to get started. The code below is ready to drop right into your app, and then you can import the new 

Explore the Powerful Customization Options Clerk Offers!

 documentation to explore more ways to customize your application using the many hooks and methods Clerks provides.

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!

Create Your Own Custom User Menu

Data breaches and password overload have made companies and their users wary of using a traditional username/password authentication system. Companies know that handling user passwords is both technically challenging 

 costly, as it requires stringent security measures, robust infrastructure for storage, and continuous monitoring to prevent unauthorized access. Users find it cumbersome to manage multiple complex passwords for various accounts, especially with the prevalence of methods like SSO, and often end up reusing passwords across different platforms, as a matter of convenience; this not only leaves the individual vulnerable, but also makes companies jobs of securing data that much harder.

Luckily, magic links have emerged as an elegant solution to secure user sessions in a 

 context. Their rising popularity is underpinned by their dual advantages:

An augmented security posture through the minimization of phishing opportunities and password theft.

An optimized user experience devoid of the need to memorize and manage many login credentials.

Magic links are a token-based authentication (TBA) strategy that uses a unique, time-sensitive URL, which leverages a securely-generated token to serve as a credential for user authentication.

The links are sent directly to the user's registered email or phone number, providing a straightforward, secure authentication method. When a user clicks on a magic link, the embedded token is validated against the server to authenticate the user's identity. This process, by design, eliminates the traditional risks associated with password-based systems and simplifies the login experience for the user.

In this guide, we will show you why you should consider magic links and how they work at a high level, before going through a Next.js App Router implementation to show how you can add magic links to your application.

Magic links bolster the security architecture of authentication systems by adopting a token-based, stateless interaction model. Each link is cryptographically unique and typically accompanied by an expiration timestamp, making it resilient against replay attacks. Given their ephemeral nature, even if a magic link were to be intercepted or exposed, its short-lived validity constrains the window of opportunity for malicious exploitation.

But there are a few other benefits to magic links for companies and users:

. Magic links eliminate the cognitive burden of remembering and managing many complex passwords, by providing a single-click authentication pathway. This frictionless access modality can enhance user engagement and satisfaction, reducing abandonment rates during the sign-in or sign-up processes.

. By using magic links to minimize passwords, organizations can reduce the risk of breaches involving personal data and avoid the consequences of compromised credentials, which can include heavy fines and reputational damage.

. With magic links, the threat of credential stuffing attacks—where compromised credentials are used to gain unauthorized access to multiple user accounts—is mitigated. Since magic links do not rely on reusable passwords, the standard vector of credential exposure is eliminated, enhancing overall system security.

. For users with disabilities or those less familiar with technology, magic links offer a more accessible authentication mode. The simplification of the login process—replacing typing and memory demands with a single action—can be particularly advantageous for individuals facing physical or cognitive challenges.

A magic link is structurally composed of two critical elements: the URL, which provides the link for the user's web interaction, and the embedded token, a cryptographically-generated string serving as the temporary credential.

In essence, a typical magic link may resemble the following structure:

https://example.com/authenticate?token=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

 query parameter carries the weight of authentication, substantiating the user's claim without revealing identity until verified by the server.

Here’s an example of how the process works:

Magic links are designed to become invalid under certain conditions for security purposes:

: The token embedded in the link has a short lifespan and is often configurable based on application security requirements.

: Once a magic link is used, it becomes invalid, preventing multiple uses, which could lead to unauthorized access.

: The system can programmatically revoke a token, thus invalidating the magic link in response to specific triggers or anomalies.

The lifecycle of a magic link commences with the generation of a unique token. This process employs cryptographic algorithms to ensure each token is a random, high-entropy string, making it virtually impossible to predict or reproduce through brute force or other cryptographic attacks. Typically, the token generation utilizes 

 to guarantee the robustness of the token against collision and preimage attacks.

Once generated, the token is stored on the server along with metadata that includes the user's identifier, the token's expiration time, and any other relevant session data. The magic link is then composed by appending the token to a predetermined URL structure, forming a complete, ready-to-use hyperlink.

This link is dispatched to the user's email address or phone number via SMTP or SMS protocols. The communication channel must be secure, leveraging TLS for email and similarly secure protocols for SMS to safeguard the link during transit.

pically interacts with the magic link by clicking on it, which initiates a secure request to the service's endpoint. The service extracts the token from the URL and verifies it against the stored data. This verification process involves several checks:

: Validates that the token matches a recently generated and stored token.

: Ensures the token has not been tampered with during transit.

: Confirms the token has not expired based on the predefined validity period.

: Ensures the token has not been used before, adhering to the principle of one-time use.

The server considers the authentication request legitimate if the token passes these checks.

Post-verification, the server establishes a session for the user. This session is typically stateless, with a new session token or cookie generated to maintain the user's authenticated state in the application. This session token is separate from the magic link token. It has its own security considerations, such as being HttpOnly and Secure, to prevent access via client-side scripts and ensure transmission over HTTPS only.

Let’s create our own magic links. We’ll use 

 13 with the App Router. We’ll also use 

 for our backend database to store users and tokens.

First, let’s create a new Next.js project:

Once you have created and configured your project, 

 to start it. You’ll see just the default Next.js homepage when you load 

Before we start building out our project, we need to install a few dependencies that we’ll use. Install them using:

: A library that allows for easy email sending.

: A library to implement JSON Web Tokens for secure data transmission.

: The Supabase client library for Javascript.

With those installed, let’s open up the project in an IDE. In total, we’re going to have two pages, two API routes, and two helper libraries:

 will be our homepage. It will have a simple email field, and will call our 

 will be the API route that will create our magic link, send it to the email address passed from 

, and save the token on our Supabase database.

 will be the API route called when the user clicks on the magic link in their email. It will verify the token and redirect the user to the protected dashboard page.

 will be a simple mock “protected page” (that would require the user to be logged in to view it).

 will be a number of database helper functions to save, load, and delete Supabase data.

Let’s start with what the user will see, page.js:

 component, which is responsible for handling the functionality of requesting a magic link via an email address. This component provides a UI for users to request a magic link. Users enter their email and submit the form, triggering a request to the server. Feedback is given to the user through messages and button state changes during the process.

First, we set up the state variables for the page. In the Next.js App Router, you can only use 

 in client-side components. As all components default to server-side, we have to use the 

 directive at the top of the file to show this page has to be rendered on the client. We have three state variables:

: Stores the user's email address. It's updated every time the user types into the email input field.

: Used to display messages to the user, like confirmation or error messages.

: Indicates whether the request is being processed. It's used to disable the submit button and change the button text while the request is in progress.

 function. This is triggered when the form is submitted, and initially prevents the default form submission action with 

 to indicate the start of an asynchronous operation and clears any previous messages stored in 

Then, comes the core part of the component. We make an async 

 endpoint with the user's email in the request body. We then update the 

 state based on the success or failure of the request:

If the request fails, it displays an error message, either from the response or a generic error message.

We have some basic error catching, and then set 

The actual form presented to the user is basic, with just an email input field that updates the 

 state variable on change and a submit button that is disabled and changes its text based on the 

 to send the form details and a paragraph that displays any messages stored in the 

This code handles the API requests related to generating and sending the magic link for user authentication. Let's go through the major components and functions of the code.

 (response) objects as parameters, and then extracts the 

 from the request's JSON body. We then use 

 to search for a user in the database using the provided email. If the user doesn’t exist we send a JSON response indicating the user was not found.

The function then creates the token using 

 to create a JWT with the user's email, signing it with a secret from environment variables and setting an expiration of 1 hour. With that token we can create our magic link. We retrieve the host from the request headers and construct a URL with the generated token as a query parameter.

The generated token is then saved in the database with an associated user ID using 

 transporter with SMTP settings (host, port, security, and authentication credentials) and send an email to the user with the magic link.

Finally, we send back a JSON response indicating that the magic link was sent.

Here, we using one of our helper libraries, 

This is a collection of utility functions designed to interact with Supabase. Each function is designed to interact with specific tables in a Supabase database, which each handle different aspects like token generation, user lookup, token validation, and cleanup. Let's break down each function:

: To save a newly generated token in the database.

 table in Supabase with the user's ID, the token, and an expiration time (set to 1 hour ahead of the current time).

If an error occurs during the database operation, it throws an error with the message received from Supabase.

Returns the data received from Supabase if the operation is successful.

: To fetch a user's data from the database using their email address.

, which is the email address of the user.

 table in Supabase for a record matching the provided email address.

Logs the email and the data received for debugging purposes.

If an error occurs, it throws an error with the message from Supabase.

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.