`SignUpFuture`

Important

The APIs described here are stable, and will become the default in the next major version of clerk-js.

The SignUpFuture object holds the state of the current sign-up attempt and provides methods to drive custom sign-up flows, including email/phone verification, password, SSO, ticket-based, and Web3-based account creation.

Properties

Name
abandonAt
Type
null | number
Description
The epoch numerical time when the sign-up was abandoned by the user.
Name
createdSessionId
Type
null | string
Description
The identifier of the newly-created session. This attribute is populated only when the sign-up is complete.
Name
createdUserId
Type
null | string
Description
The identifier of the newly-created user. This attribute is populated only when the sign-up is complete.
Name
emailAddress
Type
null | string
Description
The emailAddress supplied to the current sign-up. Only supported if email address is enabled in the instance settings.
Name
existingSession?
Type
{ sessionId: string }
Description
If present, reflects that the sign-up was not able to create a new session because the identifier already exists in an existing session. Contains the ID of the existing session.
Name
firstName
Type
null | string
Description
The firstName supplied to the current sign-up. Only supported if First and last name is enabled in the instance settings.
Name
hasPassword
Type
boolean
Description
The value of this attribute is true if a password was supplied to the current sign-up. Only supported if password is enabled in the instance settings.
Name
id?
Type
string
Description
The unique identifier of the current sign-up.
Name
isTransferable
Type
boolean
Description
Indicates that there is a matching user for provided identifier, and that the sign-up can be transferred to a sign-in.
Name
lastName
Type
null | string
Description
The lastName supplied to the current sign-up. Only supported if First and last name is enabled in the instance settings.
Name
legalAcceptedAt
Type
null | number
Description
The epoch numerical time when the user agreed to the legal compliance documents.
Name
locale
Type
string
Description
The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.
Name
missingFields
Type
SignUpField[]
Description
An array of all the fields whose values are not supplied yet but they are mandatory in order for a sign-up to be marked as complete.
Name
optionalFields
Type
SignUpField[]
Description
An array of all the fields that can be supplied to the sign-up, but their absence does not prevent the sign-up from being marked as complete.
Name
phoneNumber
Type
null | string
Description
The phoneNumber supplied to the current sign-up in E.164 format. Only supported if phone number is enabled in the instance settings.
Name
requiredFields
Type
SignUpField[]
Description
An array of all the required fields that need to be supplied and verified in order for this sign-up to be marked as complete and converted into a user.
Name
status
Type
'missing_requirements' | 'complete' | 'abandoned'
Description
The status of the current sign-up.
Name
unsafeMetadata
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.
Name
unverifiedFields
Type
SignUpIdentificationField[]
Description
An array of all the fields whose values have been supplied, but they need additional verification in order for them to be accepted. Examples of such fields are email_address and phone_number.
Name
username
Type
null | string
Description
The username supplied to the current sign-up. Only supported if username is enabled in the instance settings.
Name
verifications
Type
SignUpFutureVerifications
Description
An object that contains information about all available verification strategies.
Name
web3Wallet
Type
null | string
Description
The Web3 wallet address supplied to the current sign-up, made up of 0x + 40 hexadecimal characters. Only supported if Web3 authentication is enabled in the instance settings.

Methods

`create()`

Creates a new SignUp instance initialized with the provided parameters. The instance maintains the sign-up lifecycle state through its status property, which updates as the authentication flow progresses. Will also deactivate any existing sign-up process the client may already have in progress.

What you must pass to params depends on which sign-up options you have enabled in your app's settings in the Clerk Dashboard.

Important

The signUp.create() method is intended for advanced use cases. For most use cases, prefer the use of the factor-specific methods such as signUp.password(), signUp.sso(), etc.

Warning

Once the sign-up process is complete, call the signUp.finalize() method to set the newly created session as the active session.

function create(params: SignUpFutureCreateParams): Promise<{ error: ClerkError | null }>

Name
emailAddress?
Type
string
Description
The user's email address. Only supported if Email address is enabled. Keep in mind that the email address requires an extra verification process.
Name
firstName?
Type
string
Description
The user's first name. Only supported if First and last name is enabled in the instance settings.
Name
lastName?
Type
string
Description
The user's last name. Only supported if First and last name is enabled in the instance settings.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
locale?
Type
string
Description
The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.
Name
phoneNumber?
Type
string
Description
The user's phone number in E.164 format. Only supported if phone number is enabled. Keep in mind that the phone number requires an extra verification process.
Name
ticket?
Type
string
Description
The ticket or token generated from the Backend API. Required if strategy is set to 'ticket'.
Name
transfer?
Type
boolean
Description
When set to true, the SignUp will attempt to retrieve information from the active SignIn instance and use it to complete the sign-up process. This is useful when you want to seamlessly transition a user from a sign-in attempt to a sign-up attempt.
Name
unsafeMetadata?
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.
Name
username?
Type
string
Description
The user's username. Only supported if username is enabled in the instance settings.
Name
web3Wallet?
Type
string
Description
The Web3 wallet address, made up of 0x + 40 hexadecimal characters. Required if Web3 authentication is enabled.

`finalize()`

Converts a sign-up with status === 'complete' into an active session. Will cause anything observing the session state (such as the useUser() hook) to update automatically.

function finalize(params?: SignUpFutureFinalizeParams): Promise<{ error: ClerkError | null }>

Name
navigate?
Type
(opts: { session: SessionResource }) => Promise<unknown>
Description
A custom navigation function to be called just before the session and/or organization is set.

`password()`

Performs a password-based sign-up.

function password(params: SignUpFuturePasswordParams): Promise<{ error: ClerkError | null }>

Name
firstName?
Type
string
Description
The user's first name. Only supported if First and last name is enabled in the instance settings.
Name
lastName?
Type
string
Description
The user's last name. Only supported if First and last name is enabled in the instance settings.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
locale?
Type
string
Description
The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.
Name
unsafeMetadata?
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.
Name
password
Type
string
Description
The user's password. Only supported if password is enabled.
Name
emailAddress?
Type
string
Description
The user's email address. Only supported if Email address is enabled. Keep in mind that the email address requires an extra verification process.
Name
phoneNumber?
Type
string
Description
The user's phone number in E.164 format. Only supported if phone number is enabled. Keep in mind that the phone number requires an extra verification process.
Name
username?
Type
string
Description
The user's username. Only supported if username is enabled in the instance settings.

`reset()`

Resets the current sign-up attempt by clearing all local state back to null. This is useful when you want to allow users to go back to the beginning of the sign-up flow (e.g., to change their identifier during verification). Unlike other methods, reset() does not trigger the fetchStatus to change to 'fetching' and does not make any API calls - it only clears local state.

function reset(): Promise<{ error: ClerkError | null }>

`sso()`

Performs an SSO-based sign-up (OAuth or Enterprise).

function sso(params: SignUpFutureSSOParams): Promise<{ error: ClerkError | null }>

Name
redirectCallbackUrl
Type
string
Description
The URL or path to redirect to if a session was not created, and needs additional information.
Name
redirectUrl
Type
string
Description
The URL or path to navigate to after the OAuth or SAML flow completes. Can be provided as a relative URL (such as /dashboard), in which case it will be prefixed with the base URL of the current page.
Name
strategy
Type
OAuthStrategy | 'enterprise_sso'
Description
The strategy to use for authentication.
Name
emailAddress?
Type
string
Description
The email address to use for targeting an enterprise connection at sign-up.
Name
firstName?
Type
string
Description
The user's first name. Only supported if First and last name is enabled in the instance settings.
Name
lastName?
Type
string
Description
The user's last name. Only supported if First and last name is enabled in the instance settings.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
locale?
Type
string
Description
The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.
Name
oidcPrompt?
Type
string
Description
The value to pass to the OIDC prompt parameter in the generated OAuth redirect URL.
Name
popup?
Type
Window
Description
If provided, a Window to use for the OAuth flow. Useful in instances where you cannot navigate to an OAuth provider.
Name
unsafeMetadata?
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

`ticket()`

Performs a ticket-based sign-up.

function ticket(params?: SignUpFutureTicketParams): Promise<{ error: ClerkError | null }>

Name
firstName?
Type
string
Description
The user's first name. Only supported if First and last name is enabled in the instance settings.
Name
lastName?
Type
string
Description
The user's last name. Only supported if First and last name is enabled in the instance settings.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
locale?
Type
string
Description
The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.
Name
ticket
Type
string
Description
The ticket or token generated from the Backend API. Required if strategy is set to 'ticket'.
Name
unsafeMetadata?
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

`update()`

Updates the current SignUpFuture instance.

function update(params: SignUpFutureUpdateParams): Promise<{ error: ClerkError | null }>

Name
firstName?
Type
string
Description
The user's first name. Only supported if First and last name is enabled in the instance settings.
Name
lastName?
Type
string
Description
The user's last name. Only supported if First and last name is enabled in the instance settings.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
locale?
Type
string
Description
The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.
Name
unsafeMetadata?
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

`verifications`

An interface that represents the available verification strategies for a sign-up attempt.

Name
emailAddress
Type
SignUpVerificationResource
Description
An object holding information about the email address verification.
Name
phoneNumber
Type
SignUpVerificationResource
Description
An object holding information about the phone number verification.
Name
web3Wallet
Type
VerificationResource
Description
An object holding information about the Web3 wallet verification.
Name
externalAccount
Type
VerificationResource
Description
An object holding information about the external account verification.
Name
emailLinkVerification
Type
{ status: 'verified' | 'expired' | 'failed' | 'client_mismatch'; createdSessionId: string; verifiedFromTheSameClient: boolean } | null
Description
The verification status for email link flows.

status: The verification status.

createdSessionId: The ID of the session that was created upon successful verification.

verifiedFromTheSameClient: Whether the verification was completed from the same client (browser) that initiated the email link flow.

`verifications.sendEmailCode()`

Sends an email code to verify an email address.

function sendEmailCode(): Promise<{ error: ClerkError | null }>

`verifications.sendEmailLink()`

Used to send an email link to verify an email address.

function sendEmailLink(
  params: SignUpFutureEmailLinkSendParams,
): Promise<{ error: ClerkError | null }>

Name
verificationUrl
Type
string
Description
The full URL that the user will be redirected to when they visit the email link.

`verifications.sendPhoneCode()`

Sends a phone code to verify a phone number.

function sendPhoneCode(
  params: SignUpFuturePhoneCodeSendParams,
): Promise<{ error: ClerkError | null }>

Name
channel?
Type
'sms' | 'whatsapp'
Description
The mechanism to use to send the code to the provided phone number. Defaults to 'sms'.

`verifications.verifyEmailCode()`

Verifies an email code sent with the verifications.sendEmailCode() method.

function verifyEmailCode(
  params: SignUpFutureEmailCodeVerifyParams,
): Promise<{ error: ClerkError | null }>

Name
code
Type
string
Description
The code that was sent to the user.

`verifications.verifyPhoneCode()`

Verifies a phone code sent with the verifications.sendPhoneCode() method.

function verifyPhoneCode(
  params: SignUpFuturePhoneCodeVerifyParams,
): Promise<{ error: ClerkError | null }>

Name
code
Type
string
Description
The code that was sent to the user.

`verifications.waitForEmailLinkVerification()`

Will wait for email link verification to complete or expire.

function waitForEmailLinkVerification(): Promise<{ error: ClerkError | null }>

`web3()`

Performs a Web3-based sign-up.

function web3(params: SignUpFutureWeb3Params): Promise<{ error: ClerkError | null }>

Name
firstName?
Type
string
Description
The user's first name. Only supported if First and last name is enabled in the instance settings.
Name
lastName?
Type
string
Description
The user's last name. Only supported if First and last name is enabled in the instance settings.
Name
legalAccepted?
Type
boolean
Description
A boolean indicating whether the user has agreed to the legal compliance documents.
Name
locale?
Type
string
Description
The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.
Name
strategy
Type
"web3_base_signature" | "web3_metamask_signature" | "web3_coinbase_wallet_signature" | "web3_okx_wallet_signature" | "web3_solana_signature"
Description
The verification strategy to validate the user's sign-up request.
Name
unsafeMetadata?
Type
SignUpUnsafeMetadata
Description
Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

Last updated on Mar 3, 2026

Edit on GitHub

SignUpFuture

Feedback

`SignUpFuture`