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()
Handles the completion of an email link verification flow by processing the verification status and session information from the URL parameters after a user visits an email verification link.
function handleEmailLinkVerification(
params: handleEmailLinkVerificationParams,
customNavigate?: ((to: string) => Promise<unknown>) | undefined,
): Promise<unknown>When a user visits an email verification link, they get redirected to the URL that was provided when the email link verification flow was initialized, such as calling startEmailLinkFlow({ redirectUrl: string }).
The URL will include the following query parameters: __clerk_status and __clerk_created_session.
The __clerk_status query parameter is the outcome of the verification and accepts the following values: expired, failed, loading, verified, verified_switch_tab, or client_mismatch. client_mismatch can only be a verification outcome if the Require the same device or browser setting is enabled in the Clerk Dashboard.
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.
The handleEmailLinkVerification() method takes care of finalizing the email link flow, depending on the verification outcome. If the email link verification wasn't successful, this method will throw an EmailLinkError. You can check the error's code property to investigate the cause of the error.
Parameters
handleEmailLinkVerification() accepts the following parameters:
- Name
params- Type
handleEmailLinkVerificationParams- Description
Allows you to define the URLs where the user should be redirected to on successful verification or pending/completed sign-up or sign-in attempts. If the email link is successfully verified on another device, there's a callback function parameter that allows custom code execution.
- Name
customNavigate?- Type
(to: string) => Promise<unknown>- Description
A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.
- Name
redirectUrlComplete?- Type
string | undefined- Description
The full URL to navigate to after successful email link verification on completed sign-up or sign-in on the same device.
- Name
redirectUrl?- Type
string | undefined- Description
The full URL to navigate to after successful email link verification on the same device, but without completing sign-in or sign-up.
- Name
onVerifiedOnOtherDevice?- Type
() => void- Description
Callback function to be executed after successful email link verification on another device.
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>- Name
params- Type
HandleOAuthCallbackParams- Description
Additional props that define where the user will be redirected to at the end of a successful OAuth flow.
- Name
customNavigate- Type
(to: string) => Promise<unknown>- Description
A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.
- Name
signInUrl?- Type
string- Description
Full URL or path where the SignIn component is mounted.
- Name
signUpUrl?- Type
string- Description
Full URL or path where the SignUp component is mounted.
- Name
signInFallbackRedirectUrl?- Type
string- Description
The fallback URL to redirect to after the user signs in, if there's no
redirect_urlin the path already. Defaults to/. It's recommended to use the environment variable instead.
- Name
signUpFallbackRedirectUrl?- Type
string- Description
The fallback URL to redirect to after the user signs up, if there's no
redirect_urlin the path already. Defaults to/. It's recommended to use the environment variable instead.
- Name
signInForceRedirectUrl?- Type
string- Description
If provided, this URL will always be redirected to after the user signs in. It's recommended to use the environment variable instead.
- Name
signUpForceRedirectUrl?- Type
string- Description
If provided, this URL will always be redirected to after the user signs up. It's recommended to use the environment variable instead.
- Name
firstFactorUrl- Type
string | undefined- Description
Full URL or path to navigate during sign in, if identifier verification is required.
- Name
secondFactorUrl- Type
string | undefined- Description
Full URL or path to navigate during sign in, if 2FA is enabled.
- Name
resetPasswordUrl- Type
string- Description
Full URL or path to navigate during sign in, if the user is required to reset their password.
- Name
continueSignUpUrl- Type
string | undefined | null- Description
Full URL or path to navigate after an incomplete sign up.
- Name
verifyEmailAddressUrl- Type
string | undefined | null- Description
Full URL or path to navigate after requesting email verification.
- Name
verifyPhoneNumberUrl- Type
string | undefined | null- Description
Full URL or path to navigate after requesting phone verification.
- Name
transferable?- Type
boolean- Description
Indicates whether or not sign in attempts are transferable to the sign up flow. Defaults to
true. When set tofalse, prevents opaque sign ups when a user attempts to sign in via OAuth with an email that doesn't exist. See OAuth account transfer flows for more information.
handleUnauthenticated()
Handles a 401 response from Frontend API by refreshing the client and session object accordingly.
function handleUnauthenticated(opts?: { broadcast: boolean }): Promise<unknown>Feedback
Last updated on