Docs

SignUp

The SignUp object holds the state of the current sign-up and provides helper methods to navigate and complete the sign-up process. Once a sign-up is complete, a new user is created.

The following steps outline the sign-up process:

  1. Initiate the sign-up process by collecting the user's authentication information and passing the appropriate parameters to the create() method.
  2. Prepare the verification.
  3. Attempt to complete the verification.
  4. If the verification is successful, set the newly created session as the active session by passing the SignIn.createdSessionId to the setActive() method on the Clerk object.

Properties

  • Name
    id
    Type
    string | undefined
    Description

    The unique identifier of the current sign-up.

  • Name
    status
    Type
    'missing_requirements' | 'complete' | 'abandoned' | null
    Description

    The status of the current sign-up. The following values are supported:

    • missing_requirements: There are required fields that are either missing or they are unverified.
    • complete: All the required fields have been supplied and verified, so the sign-up is complete and a new user and a session have been created.
    • abandoned: The sign-up has been inactive for a long period of time, thus it's considered as abandoned and need to start over.
  • Name
    requiredFields
    Type
    string[]
    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
    optionalFields
    Type
    string[]
    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
    missingFields
    Type
    string[]
    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
    unverifiedFields
    Type
    string[]
    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 emailAddress and phoneNumber.

  • Name
    verifications
    Type
    SignUpVerifications
    Description

    An object that contains information about all the verifications that are in-flight.

  • Name
    username
    Type
    string | null
    Description

    The username supplied to the current sign-up. This attribute is available only if usernames are enabled. Check the available instance settings in your Clerk Dashboard for more information.

  • Name
    emailAddress
    Type
    string | null
    Description

    The email address supplied to the current sign-up. This attribute is available only if the selected contact information includes email address. Check the available instance settings for more information.

  • Name
    phoneNumber
    Type
    string | null
    Description

    The phone number supplied to the current sign-up. This attribute is available only if the selected contact information includes phone number. Check the available instance settings for more information.

  • Name
    web3Wallet
    Type
    string | null
    Description

    The Web3 wallet address, made up of 0x + 40 hexadecimal characters. This attribute is available only if Web3 authentication is enabled. Check the available instance settings for more information.

  • Name
    hasPassword
    Type
    boolean
    Description

    The value of this attribute is true if a password was supplied to the current sign-up. This attribute is available only if password-based authentication is enabled. Check the available instance settings for more information.

  • Name
    firstName
    Type
    string | null
    Description

    The first name supplied to the current sign-up. This attribute is available only if name is enabled in personal information. Check the available for more information. lastName

  • Name
    lastName
    Type
    string | null
    Description

    The last name supplied to the current sign-up. This attribute is available only if name is enabled in personal information. Check the available instance settings for more information.

  • Name
    unsafeMetadata
    Type
    {[string]: any} | null
    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
    createdSessionId
    Type
    string | null
    Description

    The identifier of the newly-created session. This attribute is populated only when the sign-up is complete.

  • Name
    createdUserId
    Type
    string | null
    Description

    The identifier of the newly-created user. This attribute is populated only when the sign-up is complete.

  • Name
    abandonAt
    Type
    number | null
    Description

    The epoch numerical time when the sign-up was abandoned by the user.

Methods

create()

Returns a new SignUp object based on the params you pass to it, stores the sign-up lifecycle state in the status property, and deactivates any existing sign-up process the client may already have in progress. Use this method to initiate a new sign-up process.

What you must pass to params depends on which sign-up options you have enabled in your Clerk application instance.

Optionally, 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, pass the createdSessionId to the setActive() method on the Clerk object. This will set the newly created session as the active session.

function create(params: SignUpCreateParams): Promise<SignUpResource>

SignUpCreateParams

  • Name
    firstName
    Type
    string | null
    Description

    The user's first name. This option is available only if name is selected in personal information. Please check the instance settings for more information.

  • Name
    lastName
    Type
    string | null
    Description

    The user's last name. This option is available only if name is selected in personal information. Please check the instance settings for more information.

  • Name
    password
    Type
    string | null
    Description

    The user's password. This option is available only if password-based authentication is selected. Please check the instance settings for more information.

  • Name
    gender
    Type
    string | null
    Description

    The user's gender. This option is available only if gender is selected in personal information. Please check the instance settings for more information.

  • Name
    emailAddress
    Type
    string | null
    Description

    The user's email address. This option is available only if email address is selected in contact information. Keep in mind that the email address requires an extra verification process. Please check the instance settings for more information.

  • Name
    phoneNumber
    Type
    string | null
    Description

    The user's phone number. This option is available only if phone number is selected in contact information. Keep in mind that the phone number requires an extra verification process. Please check the instance settings for more information.

  • Name
    web3Wallet
    Type
    string | null
    Description

    The Web3 wallet address, made up of 0x + 40 hexadecimal characters. This attribute is available only if Web3 authentication is enabled. Check the available instance settings for more information.

  • Name
    username
    Type
    string | null
    Description

    The user's username. This option is available only if usernames are enabled. Please check the instance settings for more information.

  • Name
    unsafeMetadata
    Type
    {[string]: any} | null
    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
    strategy
    Type
    'oauth_<provider>' | 'saml' | 'ticket'
    Description

    The strategy to use for the sign-up flow. The following strategies are supported:

    • oauth_<provider>: The user will be authenticated with their social sign-in account. See available social providers.
    • saml: The user will be authenticated with SAML.
    • ticket: The user will be authenticated via the ticket or token generated from the Backend API.
    • google_one_tap: The user will be authenticated with the Google One Tap UI. It's recommended to use authenticateWithGoogleOneTap() instead, as it will also set the user's current session as active for you.
  • Name
    redirectUrl (deprecated)
    Type
    string
    Description

    The redirect URL after the sign-up flow has completed. signInFallbackRedirectUrl has priority over the deprecated redirectUrl. Use fallbackRedirectUrl or forceRedirectUrl instead of redirectUrl.

  • Name
    actionCompleteRedirectUrl?
    Type
    string
    Description

    The URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign in. This parameter is required only if strategy is set to an OAuth strategy like oauth_<provider>, or set to saml.

  • Name
    ticket
    Type
    string
    Description

    Provide the ticket or token generated from the Backend API. This parameter is required only if strategy is set to ticket.

  • Name
    transfer
    Type
    boolean
    Description

    Transfer the user to a dedicated sign-up for an OAuth flow.

update()

This method is used to update the current sign-up.

As with create, the form of the given params depends on the configuration of the instance.

function update(params: SignUpUpdateParams): Promise<SignUpResource>

SignUpUpdateParams

SignUpUpdateParams is a mirror of SignUpCreateParams with the same fields and types.

function createEmailLinkFlow(): {
  startEmailLinkFlow: (params: StartEmailLinkFlowParams) => Promise<SignUp>
  cancelEmailLinkFlow: () => void
}

Sets up a sign-up with email link flow. Calling createEmailLinkFlow() will return two functions.

The first function is async and starts the email link flow, preparing an email link verification. It sends the email link email and starts polling for verification results. The signature is startEmailLinkFlow({ redirectUrl: string }) => Promise<SignUpResource>.

The second function can be used to stop polling at any time, allowing for full control of the flow and cleanup. The signature is cancelEmailLinkFlow() => void.

function createEmailLinkFlow(): {
  startEmailLinkFlow: (params: StartEmailLinkFlowParams) => Promise<SignUpResource>
  cancelEmailLinkFlow: () => void
}

createEmailLinkFlow returns an object with two functions:

  • Name
    startEmailLinkFlow
    Type
    (params: StartEmailLinkFlowParams) => Promise<SignUp>
    Description

    Function to start the email link flow. It prepares an email link verification and polls for the verification result.

  • Name
    redirectUrl
    Type
    string
    Description

    The email link target URL. Users will be redirected here once they click the email link from their email.

Additional methods

In addition to the methods listed above, the SignUp class also has the following methods:

Authenticate with

Verification

Email verification

Phone verification

Web3 verification

Example

For examples of how to access the SignUp object and use the associated methods, see the custom flow guides.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on