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.
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 accepts the following values: verified
, failed
, expired
, or client_mismatch
. client_mismatch
can only be a verification outcome if the Require the same device or browser setting is turned on for sign-ins and sign-ups.
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.
If the email link verification failed or the link expired, this method will throw a EmailLinkError
. Check the error's code
property for details.
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.
Parameters
- Name
params
- Type
handleEmailLinkVerificationParams
- Description
Allows you to define the URLs where the user should be redirected to on successful verification and:
- Completed sign in or sign up attempt.
- Pending sign in or sign up attempt.
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
Allows you to define a custom navigation function.
- Name
redirectUrlComplete?
- Type
string | undefined
- Description
Full URL or path to navigate after successful email link verification on completed sign up or sign in on the same device.
- Name
redirectUrl?
- Type
string | undefined
- Description
Full URL or path to navigate after successful email link verification on the same device, but not completed 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)
.
- 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
Allows you to define a custom navigation function.
- 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_url
in 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_url
in 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 details.
handleUnauthenticated()
Handles a 401 response from Frontend API by refreshing the client and session object accordingly.
Feedback
Last updated on