Docs

Sign-in components

The following components are used when creating sign-in flows. They are imported from @clerk/elements/sign-in. It is recommended to import them all under the SignIn namespace to make discovery easier and reduce naming conflicts with other components throughout your application. The code snippets on this page assume you have imported the components this way.

Anatomy
import * as SignIn from '@clerk/elements/sign-in'

export default function SignInPage() {
  return (
    <SignIn.Root>
      <SignIn.Step name="start" />
      <SignIn.Step name="verifications" />
      <SignIn.Step name="choose-strategy" />
      <SignIn.Step name="forgot-password" />
      <SignIn.Step name="reset-password" />
    </SignIn.Root>
  )
}

<Root>

The root sign-in component. Sets up providers and state management for the sign-in flow. Must wrap all other sign-in components.

<Root> will validate your sign-in flow to ensure the implementation is correct based on instance settings and best practices. In development instances, if the flow is invalid, it will throw an error.

Properties

  • Name
    path?
    Type
    string
    Description

    The root path the sign-in flow is mounted at. If not provided, will be automatically inferred (either through the current pathname or environment variables). Fallback: /sign-in

  • Name
    fallback?
    Type
    React.ReactNode
    Description

    Fallback markup to render while Clerk is loading. Default: null

  • Name
    routing?
    Type
    'path' | 'virtual'
    Description

    If you want to render Clerk Elements in e.g. a modal, use the 'virtual' routing mode. Default: 'path'

The following data attributes are also added to the underlying element:

<Step>

A step in the sign-in flow. Conditionally renders its children based on the status of the current sign-in attempt. start is the initial step.

Properties

  • Name
    name
    Type
    'start' | 'verifications' | 'choose-strategy' | 'forgot-password' | 'reset-password'
    Description

    The name of the step for which its children will be rendered.

<Step name="start">

Renders the beginning sign-in form. Once a sign-in attempt has been created from this step, <Step name="verifications"> will be rendered.

Typically, this step will contain an identifier field and social connection buttons to create a sign-in attempt, however the exact fields that should be rendered depend on your instance configuration.

Usage

page.tsx
<SignIn.Step name="start">
  <Clerk.Field name="identifier">
    <Clerk.Label>Email</Clerk.Label>
    <Clerk.Input />
    <Clerk.FieldError />
  </Clerk.Field>
  <SignIn.Action submit>Sign In with Email</SignIn.Action>
</SignIn.Step>

<Step name="verifications">

Will render its children if a sign-in attempt is in progress. Any nested <Strategy> components will conditionally render based on the status of the sign-in attempt.

You'll typically also want to link to choose-strategy to allow for alternative login methods.

Usage

page.tsx
<SignIn.Step name="verifications">
  <SignIn.Strategy name="password">
    <Clerk.Field name="password">
      <Clerk.Label>password</Clerk.Label>
      <Clerk.Input />
      <Clerk.FieldError />
    </Clerk.Field>
    <SignIn.Action submit>Sign In</SignIn.Action>
  </SignIn.Strategy>
  <SignIn.Action navigate="choose-strategy">Use another method</SignIn.Action>
</SignIn.Step>

<Step name="choose-strategy">

Allows a user to pick a new strategy to verify. This step can be rendered by navigating to choose-strategy using <Action>.

Usage

page.tsx
<SignIn.Step name="choose-strategy">
  <SignIn.SupportedStrategy name="phone_code">Send a code to your phone</SignIn.SupportedStrategy>
</SignIn.Step>

<Step name="forgot-password">

If the currently requested strategy is password, but a user can't remember their password, you can navigate them to the forgot-password step. They can begin the reset password flow or choose a new strategy. This step can be rendered by navigating to forgot-password using <Action>.

Usage

page.tsx
<SignIn.Step name="forgot-password">
  <SignIn.SupportedStrategy name="reset_password_email_code">
    Reset your password via Email
  </SignIn.SupportedStrategy>
  <p>or</p>
  <SignIn.SupportedStrategy name="google">Sign in with Google</SignIn.SupportedStrategy>
</SignIn.Step>

<Step name="reset-password">

If a user has requested a password reset and verified their identity, they will be navigated to reset-password. A password field should be rendered in this step to allow the user to set a new password.

Usage

page.tsx
<SignIn.Step name="reset-password">
  <Clerk.Field name="password">
    <Clerk.Label>New password</Clerk.Label>
    <Clerk.Input />
    <Clerk.FieldError />
  </Clerk.Field>
  <Clerk.Field name="confirmPassword">
    <Clerk.Label>Confirm password</Clerk.Label>
    <Clerk.Input />
    <Clerk.FieldError />
  </Clerk.Field>
  <SignIn.Action submit>Update password</SignIn.Action>
</SignIn.Step>

<Strategy>

Conditionally renders its children depending on the authentication strategy that needs to be verified. Does not render any markup on its own.

Properties

  • Name
    name
    Type
    'saml' | 'ticket' | 'password' | 'passkey' | 'phone_code' | 'email_code' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'reset_password_email_code' | 'reset_password_phone_code' | 'email_link' | 'totp' | 'backup_code' | 'oauth' | 'web3' | OAuthStrategy
    Description

    The name of the strategy for which its children will be rendered.

Usage

page.tsx
<SignIn.Strategy name="email_code">
  <Clerk.Field name="code">
    <Clerk.Label>Code</Clerk.Label>
    <Clerk.Input />
    <Clerk.FieldError />
  </Clerk.Field>
  <SignIn.Action submit>Verify</SignIn.Action>
</SignIn.Strategy>

<Strategy name="passkey">

page.tsx
<SignIn.Strategy name="passkey">
  <SignIn.Action submit>Continue with Passkey</SignIn.Action>
</SignIn.Strategy>

<SupportedStrategy>

Renders a button that will change the current strategy that needs to be verified when in the choose-strategy or forgot-password steps.

Properties

  • Name
    name
    Type
    'email_code' | 'email_link' | 'password' | 'passkey' | 'phone_code' | 'reset_password_email_code' | 'reset_password_phone_code' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature'
    Description

    The name of the strategy to switch to.

Usage

page.tsx
<SignIn.Step name="choose-strategy">
  <SignIn.SupportedStrategy name="password">Sign in with password</SignIn.SupportedStrategy>
</SignIn.Step>

<Action>

Exposes various flow-related actions. It can be used to submit forms, navigate between steps, and re-trigger sending of verification codes. By default, renders a <button>.

Properties

  • Name
    submit?
    Type
    boolean
    Description

    If true, the action will submit the form. Default: false

  • Name
    navigate?
    Type
    'choose-strategy' | 'forgot-password' | 'previous' | 'start'
    Description

    The name of the step to navigate to. Default: undefined

  • Name
    resend?
    Type
    boolean
    Description

    If true, the action will resend the verification code for the currently active strategy, if applicable. Default: false

  • Name
    fallback?
    Type
    ({ resendableAfter: number }) => React.ReactNode
    Description

    Only used when resend is true. If provided, the fallback markup will be rendered before the resend delay has expired. Default: null

Usage

<Action submit>

page.tsx
<SignIn.Step name="start">
  <Clerk.Field name="identifier">
    <Clerk.Label>Email</Clerk.Label>
    <Clerk.Input />
    <Clerk.FieldError />
  </Clerk.Field>
  <SignIn.Action submit>Sign in</SignIn.Action>
</SignIn.Step>

<Action navigate>

page.tsx
<SignIn.Step name="verifications">
  <SignIn.Strategy name="password">
    <Clerk.Field name="password">
      <Clerk.Label>Password</Clerk.Label>
      <Clerk.Input />
      <Clerk.FieldError />
    </Clerk.Field>
    <SignIn.Action submit>Sign in</SignIn.Action>
    <SignIn.Action navigate="forgot-password">Forgot password?</SignIn.Action>
  </SignIn.Strategy>
</SignIn.Step>

<Action resend>

page.tsx
<SignIn.Step name="verifications">
  <SignIn.Strategy name="email_code">
    <Clerk.Field name="code">
      <Clerk.Label>Code</Clerk.Label>
      <Clerk.Input />
      <Clerk.FieldError />
    </Clerk.Field>
    <SignIn.Action submit>Verify</SignIn.Action>
    <SignIn.Action
      resend
      fallback={({ resendableAfter }) => <p>Resend code in {resendableAfter} second(s)</p>}
    >
      Resend code
    </SignIn.Action>
  </SignIn.Strategy>
</SignIn.Step>

<SafeIdentifier />

Renders a masked identifier corresponding to the parent Strategy or SupportedStrategy, falling back to the identifier that has been provided by the user during a sign-in attempt. Renders a string (or empty string if it can't find an identifier). Must be a child of either <Strategy> or <SupportedStrategy>.

Properties

  • Name
    transform?
    Type
    (identifier: string) => string
    Description

    If provided, modify the supplied identifier string before rendering. Useful when interpolating the identifier into localized strings.

Usage

page.tsx
<SignIn.Strategy name="email_code">
  <h1>Check your email</h1>
  <p>
    We sent a code to <SignIn.SafeIdentifier />.
  </p>
</SignIn.Strategy>
page.tsx
<SignIn.Strategy name="email_code">
  <h1>{t('checkEmail')}</h1>
  <p>
    <SignIn.SafeIdentifier transform={(identifier) => t('sentCodeTo', { identifier })} />
  </p>
</SignIn.Strategy>

<Salutation />

Renders a salutation for the user during a sign-in attempt. It attempts to resolve these values in this specific order:

  1. First name
  2. Last name
  3. Identifier

Renders a string (or empty string if it can't find an identifier).

Usage

page.tsx
<SignIn.Strategy name="password">
  <p>
    Welcome back <SignIn.Salutation />!
  </p>
</SignIn.Strategy>

<Passkey />

Trigger an autofill suggestion dialog with the stored passkeys. After selecting a passkey a sign-in attempt will be created. By default, renders a <button>.

Usage

page.tsx
<SignIn.Step name="start">
  <SignIn.Passkey>Continue with Passkey</SignIn.Passkey>
</SignIn.Step>

Feedback

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

Last updated on