Handle navigation
These are all methods on the Clerk class that help you handle navigation callbacks from Clerk, usually in conjunction with redirect methods or built URLs.
handleEmailLinkVerification()
Completes an email link verification flow once we've reached the email link results URL.
function handleEmailLinkVerification( params: handleEmailLinkVerificationParams, customNavigate?: ((to: string) => Promise<unknown>) | undefined ): Promise<unknown>;
When users click on email links they get redirected to the URL that was provided during email link verification flow initialization. The URL will contain a couple of important query parameters added by Clerk. These are called __clerk_status and __clerk_created_session.
The __clerk_status query parameter is the outcome of the verification and can take three values: verified, failed or expired.
The __clerk_created_session query parameter will hold the ID of the new session, if one was created as a result of the verification. Since the email link can be opened at any device and not the one that originated the verification, the new session ID might not be available under Client.sessions.
Email link flows can be completed on the same device that they were initiated or on a completely different browser. For example, a user might start the email link flow on their desktop browser, but click on the email link from their mobile phone.
The handleEmailLinkVerification() method takes care of finalizing the email link flow, depending on the verification outcome.
Upon successful verification, the method will figure out if the sign in or sign up attempt was completed and redirect the user accordingly. As such, it accepts different parameters for the URL it should redirect when sign-in or sign-up is completed and the URL which it should redirect when the sign-in or sign-up attempt is still pending. Both parameters are optional, but you can provide them to the method up front. The final redirect will depend on the sign-in or sign-up attempt's status.
Additionally, the handleEmailLinkVerification() method allows you to execute a callback if the successful verification happened on another device.
In case the email link verification wasn't successful, the handleEmailLinkVerification() method will throw a EmailLinkError. You can check the error's code property to see if the email link expired, or the verification simply failed.
Take a look at the function parameters description below for more usage details.
handleEmailLinkVerification() params
| Name | Type | Description |
|---|---|---|
params | handleEmailLinkVerificationParams | Allows you to define the URLs where the user should be redirected to on successful verification and:
If the email link is successfully verified on another device, there's a callback function parameter that allows custom code execution. |
customNavigate? | (to: string) => Promise<unknown> | Allows you to define a custom navigation function. |
handleEmailLinkVerificationParams
| Name | Type | Description |
|---|---|---|
redirectUrlComplete? | string | undefined | Full URL or path to navigate after successful email link verification on completed sign up or sign in on the same device. |
redirectUrl? | string | undefined | Full URL or path to navigate after successful email link verification on the same device, but not completed sign in or sign up. |
onVerifiedOnOtherDevice? | () => void | Callback function to be executed after successful email link verification on another device. |
handleEmailLinkVerification() returns
| Type | Description |
|---|---|
Promise<unknown> | This method will throw a EmailLinkError if the email link verification failed or the link expired. Check the error's code property for details. |
handleRedirectCallback()
Completes a custom OAuth flow started by calling either SignIn.authenticateWithRedirect(params) or SignUp.authenticateWithRedirect(params).
function handleRedirectCallback( params: HandleOAuthCallbackParams, customNavigate?: ((to: string) => Promise<unknown>) | undefined ): Promise<unknown>;
handleRedirectCallback() params
| Name | Type | Description |
|---|---|---|
params | HandleOAuthCallbackParams | Additional props that define where the user will be redirected to at the end of a successful OAuth flow. |
customNavigate | (to: string) => Promise<unknown> | Allows you to define a custom navigation function. |
HandleOAuthCallbackParams
| Name | Type | Description |
|---|---|---|
afterSignUpUrl | string | undefined | null | Full URL or path to navigate after successful sign up. Defaults to /. It's recommended to use the environment variable instead. |
afterSignInUrl | string | undefined | null | Full URL or path to navigate after successful sign in. Defaults to /. It's recommended to use the environment variable instead. |
redirectUrl | string | undefined | null | Full URL or path to navigate after successful sign in or sign up. The same as setting afterSignInUrl and afterSignUpUrl to the same value. |
firstFactorUrl | string | undefined | Full URL or path to navigate during sign in, if identifier verification is required. |
secondFactorUrl | string | undefined | Full URL or path to navigate during sign in, if 2FA is enabled. |
resetPasswordUrl | string | Full URL or path to navigate during sign in, if the user is required to reset their password. |
continueSignUpUrl | string | undefined | null | Full URL or path to navigate after an incomplete sign up. |
verifyEmailAddressUrl | string | undefined | null | Full URL or path to navigate after requesting email verification. |
verifyPhoneNumberUrl | string | undefined | null | Full URL or path to navigate after requesting phone verification. |
handleUnauthenticated()
Handles a 401 response from Frontend API(opens in a new tab) by refreshing the client and session object accordingly.
function handleUnauthenticated(opts?: { broadcast: boolean }): Promise<unknown>;
Last updated on March 6, 2024