Verify a new sign-up by email link
Email-based sign-up
Clerk · Hook
useEmailLink
useEmailLink provides Clerk's email-link authentication flow API. Use it to start a flow that emails a verification link and redirects the user to an application route for verification.
How it works
useEmailLink is the renamed Clerk hook for email-link authentication flows. It exposes the flow methods used to send a verification link and coordinate verification through a redirect URL.
Syntax
const emailLink = useEmailLink();Returns
An email-link flow object exposing methods such as startEmailLinkFlow().
Key points
- The flow's startEmailLinkFlow method sends the verification email.
- A redirectUrl is required when starting the email-link flow.
- The configured redirect route is where the application handles the returned email link.
- Use useClerk on the verification page to obtain the verification handler.
Common mistakes
- Email-link verification normally requires the user to open the link on the device and browser that initiated the flow.
Example: Start an email-link flow
import { useEmailLink } from '@clerk/react';
export function EmailLinkButton() {
const emailLink = useEmailLink();
return (
<button onClick={() => emailLink.startEmailLinkFlow({ redirectUrl: '/verify' })}>
Send verification link
</button>
);
}Starts an email-link flow and sends the user a verification link that returns to the specified route.
When to use it
Sign in an existing user through an email link
Passwordless authentication
Verify an email address added to a user profile
Account maintenance
Interview questions
QWhat is useEmailLink used for?
useEmailLink provides the email-link flow API in the current Clerk naming. The flow sends an email link, while verification is completed on the redirect page through Clerk's email-link verification method.
Follow-up: Where is verification completed? On the redirect URL, use Clerk's handleEmailLinkVerification method to process the link.
QWhy does the email-link flow need a redirect URL?
The flow must be given a redirect URL. Clerk sends the email link, and after the user visits it, Clerk redirects them to that URL so the application can complete verification.
Follow-up: What should the redirect page do? It should invoke handleEmailLinkVerification from useClerk.
QDescribe the lifecycle of an email-link verification flow.
The user starts the flow from the application, receives a verification link by email, and returns through the configured redirect route. The redirect route then invokes Clerk's verification handler.
Follow-up: What configuration is needed for sign-up or sign-in? Enable the appropriate email-link verification and email sign-in settings in the Clerk Dashboard.
Related
useClerkhandleEmailLinkVerificationcreateEmailLinkFlowstartEmailLinkFlowEmailLinkErrorCode