`SignUpFuture`

Properties
Methods

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
TKTKTK
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
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
SignUpStatus
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
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.

You can complete the sign-up process in one step if you supply the required fields to create(). Otherwise, Clerk's sign-up process provides great flexibility and allows users to easily create multi-step sign-up flows.

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: unknown }>

TKTKTK

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
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()`

Used to convert 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: unknown }>

TKTKTK

Name
navigate?
Type
SetActiveNavigate
Description
TKTKTK

`password()`

Used to sign up using an email address and password.

function password(params: SignUpFuturePasswordParams): Promise<{ error: unknown }>

TKTKTK

Name
password
Type
string
Description
The user's password. Only supported if password is enabled.

`sso()`

Used to create an account using an OAuth connection.

function sso(params: SignUpFutureSSOParams): Promise<{ error: unknown }>

TKTKTK

Name
redirectCallbackUrl
Type
string
Description
TODO @revamp-hooks: This should be handled by FAPI instead.
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
string
Description
The strategy to use for authentication.

`ticket()`

Used to perform a ticket-based sign-up.

function ticket(params?: SignUpFutureTicketParams): Promise<{ error: unknown }>

TKTKTK

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
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 SignUp.

function update(params: SignUpFutureUpdateParams): Promise<{ error: unknown }>

TKTKTK

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
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.sendEmailCode()`

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

function sendEmailCode(): Promise<{ error: unknown }>

`verifications.sendPhoneCode()`

Used to send a phone code to verify a phone number.

function sendPhoneCode(params: SignUpFuturePhoneCodeSendParams): Promise<{ error: unknown }>

TKTKTK

Name
channel?
Type
PhoneCodeChannel
Description
The mechanism to use to send the code to the provided phone number. Defaults to 'sms'.
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.

`verifications.verifyEmailCode()`

Used to verify a code sent via email.

function verifyEmailCode(params: SignUpFutureEmailCodeVerifyParams): Promise<{ error: unknown }>

TKTKTK

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

`verifications.verifyPhoneCode()`

Used to verify a code sent via phone.

function verifyPhoneCode(params: SignUpFuturePhoneCodeVerifyParams): Promise<{ error: unknown }>

TKTKTK

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

`web3()`

Used to perform a Web3-based sign-up.

function web3(params: SignUpFutureWeb3Params): Promise<{ error: unknown }>

TKTKTK

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
strategy
Type
"web3_base_signature" | "web3_metamask_signature" | "web3_coinbase_wallet_signature" | "web3_okx_wallet_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.

Edit on GitHub

Last updated on Oct 14, 2025

SignUpFuture

Feedback

`SignUpFuture`