Alt description missing in image
Beta: Plugins coming soon!
@auth/clerkhooksuseSignUpFlow

useSignUpFlow()

import { useSignUpFlow } from '@auth/clerk'
        • useSignUpFlow()

Use this hook to build custom sign-up experiences with built-in form state and verification flow. This hook wraps Clerk’s useSignUp() and our useSocialAuthFlow() to manage creating the user, sending the email verification code, and completing the session.

Usage

SignUpScreen.tsx
import { useSignUpFlow } from '@auth/clerk'
 
export const SignUpScreen = () => {
    const {
        formState,
        isLoaded,
        isLoading,
        isPendingVerification,
        onSignUpPressed,
        onVerifyCodePressed,
        signUpError,
    } = useSignUpFlow({
        forceRedirectUrl: '/',
        initialValues: { emailAddress: '', password: '' },
    })
 
    if (!isLoaded) return null
 
    return (
        <View>
            <TextInput
                value={formState.values.emailAddress}
                onChangeText={(v) => formState.setFieldValue('emailAddress', v)}
                placeholder="Email"
                autoCapitalize="none"
            />
            <TextInput
                value={formState.values.password}
                onChangeText={(v) => formState.setFieldValue('password', v)}
                placeholder="Password"
                secureTextEntry
            />
 
            {!isPendingVerification ? (
                <Button disabled={isLoading} onPress={onSignUpPressed} title="Create account" />
            ) : (
                <>
                    <TextInput
                        value={formState.values.code}
                        onChangeText={(v) => formState.setFieldValue('code', v)}
                        placeholder="Verification code"
                    />
                    <Button disabled={isLoading} onPress={onVerifyCodePressed} title="Verify email" />
                </>
            )}
 
            <Button disabled={isLoading} onPress={() => onPressSocialSignIn('oauth_google')} title="Continue with Google" />
 
            {!!signUpError && <Text>{signUpError}</Text>}
        </View>
    )
}

API

Parameters

  • forceRedirectUrl?: string | null — After success, navigate to this URL (defaults to /).
  • initialValues?: Partial<SignUpFormState> — Prefill the form state. If code is preset, the hook starts in verification mode.

Returned values

  • formState: UseFormState<SignUpFormState> — Controlled form state with values, setFieldValue, etc.
  • isLoaded: boolean — Underlying Clerk useSignUp() loaded state.
  • isLoading: boolean — Local submitting/processing state.
  • isPendingVerification: boolean — Whether the flow is waiting for the email verification code.
  • onSignUpPressed: () => Promise<void> — Creates the sign-up and triggers email verification.
  • onVerifyCodePressed: () => Promise<void> — Verifies the email code and completes the session.
  • router — Universal navigation object from useRouter().
  • signUp — Clerk signUp resource.
  • signUpStatus: SignUpStatus | null — Most recent sign-up status when not complete.
  • setActive — Clerk setActive to set the active session on success.
  • setIsLoading, setSignUpStatus, setSignUpError — Local setters.
  • signUpError: string | null — Last user-facing error message.

Form shape

type SignUpFormState = {
    emailAddress: string
    password: string
    firstName?: string
    lastName?: string
    username?: string
    phoneNumber?: string
    legalAccepted?: boolean
    code?: string // 6 digits, triggers verification mode when present
    errors?: Record<string, string[]>
}
See Clerk’s guide on error handling for custom flows: https://clerk.com/docs/guides/development/custom-flows/error-handling
useUseruseSignUp