āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/guides/customizing-clerk/elements/reference/common ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
Clerk Elements provides a set of common components that are used across all flows. It's recommended to import them all under the Clerk namespace to make discovery easier and reduce naming conflicts with other common components throughout your application. The code snippets on this page assume you have imported the components this way.
import * as Clerk from '@clerk/elements/common'
Unless otherwise mentioned, all components accept a className prop.
<Connection>Renders a social connection button based on the provided name. Throws an error in development if the provided social connection is not enabled in your instance. See Social connections (OAuth) to learn how to enable them in the Clerk Dashboard.
By default, <Connection> will be rendered as an unstyled <button>.
If true, <Connection> will render as its child element, passing along any necessary props. Default: false
namestringName of the social connection to render. </Properties>
<SignIn.Root>
<SignIn.Step name="start">
<Clerk.Connection name="google">Sign in with Google</Clerk.Connection>
</SignIn.Step>
</SignIn.Root>
You can enrich this example by providing an <Icon> to display the social connection's logo.
<Field>Associates its child elements with a specific <Input>. It automatically generates unique IDs and associates child <Label> and <Input> elements with each other.
Name for form field, will be used to associate all underlying field elements.
alwaysShow?booleanWhen true, the field will always be rendered, regardless of its state. When false, the field is hidden if it's optional or if it's a filled-out required field. Default: false
children?(state: 'success' | 'error' | 'warning' | 'info' | 'idle') => React.ReactNodeProvide a function as children and access the field's state. </Properties>
Place common components like <Input>, <FieldError>, or <Label> inside <Field>.
<Clerk.Field name="unique-name">{/* Your content */}</Clerk.Field>
The state you can access here is the same as in <FieldState>.
<Clerk.Field name="unique-name">{(state) => <p>Field's state is: {state}</p>}</Clerk.Field>
<FieldError>Renders error messages associated with a specific <Field>. By default, the error's message will be rendered in an unstyled <span>. Optionally, the children prop accepts a function to customize rendering.
Used to target a specific field by name when rendering outside of a <Field> component. Default: Automatically inferred
asChild?booleanIf true, <FieldError> will render as its child element, passing along any necessary props. Default: false
children?({ message: string, code: string }) => React.ReactNodeProvide a function as children and access the error's message and code.
</Properties>
If the <Field> is in an error state, <FieldError> will display its message.
<Clerk.Field name="unique-name">
<Clerk.FieldError />
</Clerk.Field>
By having access to both message and code you can enrich the incoming message or localize it by checking for a specific code.
<Clerk.Field name="unique-name">
<Clerk.FieldError>
{({ message, code }) => (
<span>
{message} ({code})
</span>
)}
</Clerk.FieldError>
</Clerk.Field>
<FieldState>Enables you to programmatically access additional information from the parent <Field> component. By default, you'll have access to state. state will also contain the field's ValidityState. <FieldState> is useful for implementing animations if you need direct access to the state value.
If you use <Input type="password" validatePassword>, additional information in the form of message and codes is provided.
Use this function to access the field's state. Optionally, information regarding password validation is given. </Properties>
<Input> will start with a state of idle until the user interacts with it. Depending on the user's input, the state will change to success or error.
<Clerk.Field name="emailAddress">
<Clerk.Label>Email</Clerk.Label>
<Clerk.Input />
<Clerk.FieldState>{({ state }) => <p>Field's state is: {state}</p>}</Clerk.FieldState>
</Clerk.Field>
<Input type="password" validatePassword>If you're using <Input type="password" validatePassword>, the <FieldState>'s children function receives additional arguments:
The standardized English message generated for the current state of the input. This message is generated based on the codes associated with the <FieldState>.
codes(string | [string, Record<string, string | number>])[]The error codes associated with the <FieldState>. You can use these codes to return a custom message or localize its contents.
</Properties>
Initially, the <Input> will have a state of idle until the user interacts with the input. Depending on the user's input, the state will change to 'success' | 'error' | 'warning' | 'info'.
<Clerk.Field name="password">
<Clerk.Label>Password</Clerk.Label>
<Clerk.Input type="password" validatePassword />
<Clerk.FieldState>
{({ state, codes, message }) => (
<div>
<pre>Field state: {state}</pre>
<pre>Field msg: {message}</pre>
<pre>Codes: {JSON.stringify(codes, null, 2)}</pre>
</div>
)}
</Clerk.FieldState>
</Clerk.Field>
<GlobalError />Renders errors that are returned from Clerk's API but are not associated with a specific form field. By default, renders the error's message wrapped in a <div>. Optionally, the children prop accepts a function to customize rendering. Must be a child of components like <SignIn>/<SignUp> to have access to the underlying form state.
If true, <GlobalError> will render as its child element, passing along any necessary props. Default: false
code?stringForces the message with the matching code to be shown. This is useful when using server-side validation. Default: undefined
children?({ message: string, code: string }) => React.ReactNodeProvide a function as children and access the error's message and code.
</Properties>
<SignIn.Root>
<Clerk.GlobalError />
</SignIn.Root>
By having access to both message and code you can enrich the incoming message or localize it by checking for specific code.
<SignIn.Root>
<Clerk.GlobalError>
{({ message, code }) => (
<span>
{message} ({code})
</span>
)}
</Clerk.GlobalError>
</SignIn.Root>
<Icon>By default, renders as an <img> element with the logo of the parent <Connection> as the value of its src prop. Must be a child of <Connection>.
[!TIP]
<Icon>is designed to give you access to Clerk's social connection logos and has intentionally limited customizability. If you need more customizability, consider options such as Iconify.
If true, <Icon> will render as its child element, passing along any necessary props. Default: false
</Properties>
The following example demonstrates how to render the Google social connection logo with <Icon>:
<SignIn.Root>
<SignIn.Step name="start">
<Clerk.Connection name="google">
<Clerk.Icon />
Sign in with Google
</Clerk.Connection>
</SignIn.Step>
</SignIn.Root>
<Input>Handles rendering of <input /> elements within Clerk's flows. Supports special type prop values to render input types that are unique to authentication and user management flows. Additional props will be passed through to the <input />.
[!NOTE] For screen reader accessibility, always associate a
<Label>with your<Input>elements.
If true, <Input> will render as its child element, passing along any necessary props. Default: false
name?stringName for the form field. Will be used to associate all underlying field elements. Can be automatically inferred from the name on the <Field> component.
type?'text' | 'email' | 'tel' | 'otp'* | 'password'Type for the input. Default: 'text'
autoComplete?stringRefers to the HTML attribute. If <Input> is used inside a <SignIn> flow and autoComplete="webauthn" is set, passkey autofill will be attempted.
</Properties>
[!NOTE] Values denoted with
*are unique Clerk input types.
The following data attributes are also added to the underlying element:
data-valid - If the field state is validdata-invalid - If the field state is invalid (Either the ValidityState or has an associated error from Clerk's API)date-state - Refers to the <FieldState> statusdata-has-value - If the input has a value<Clerk.Field name="identifier">
<Clerk.Label>Email</Clerk.Label>
<Clerk.Input type="email" />
</Clerk.Field>
<Input type="otp">A special type used to render an input that accepts a one-time passcode (OTP). If the corresponding <Field> has name="code", the child <Input> will default to the otp type. Only numbers are accepted as inputs, and the default max length is 6.
By default, a single text <input /> will be rendered. If provided, the render prop will be called for each character present in the input. This enables UI patterns where an OTP input is visually represented as N distinct elements.
Sets how many digits the input number can be. Default: 6
autoSubmit?booleanIf true, the form will be automatically submitted once the input is filled out. Default: false
passwordManagerOffset?numberPassword managers place their icon inside an <input />. This default behaviour is not desirable when you use the render prop to display N distinct element. With this prop you can increase the width of the <input /> so that the icon is rendered outside the OTP inputs. Default: 40
render?({ value, status }: { value: string; status: 'none' | 'selected' | 'cursor' | 'hovered' }) => React.ReactNodeA render prop function that receives the value and status of each character. value is the character to render, status is the current status of the input character.
</Properties>
The properties asChild and name from <Input> also apply to <Input type="otp">.
The following data attributes are also added to the underlying element:
data-otp-inputA single <input type="text" /> input that only allows 6 numbers to be entered. Once the user filled in all information, the form is automatically submitted.
<Clerk.Field name="code">
<Clerk.Input type="otp" autoSubmit />
</Clerk.Field>
You can render each number into an individual item and animate its appearance depending on the status.
<Clerk.Field name="code">
<Clerk.Input
type="otp"
passwordManagerOffset={40}
render={({ value, status }) => <span data-status={status}>{value}</span>}
/>
</Clerk.Field>
<Input type="password">A thin wrapper around the <input type="password" /> element to provide password validation logic. You can define password rules in the Clerk Dashboard. By default, this validation is turned off and you need to set a validatePassword prop.
Once activated, you can access the instant validation feedback through <FieldState> and display rich information to your users.
If true, password validation according to your password rules is happening while the user types in their password. Default: false
</Properties>
The following data attributes are also added to the underlying Element if validatePassword is true:
data-has-passed-validation - If the password has passed the validation or notThe existing data attributes from <Input> are also present on this Element.
For more information on how to use state, codes, and message check the <FieldState> docs.
<Clerk.Field name="password">
<Clerk.Label>Password</Clerk.Label>
<Clerk.Input type="password" validatePassword />
<Clerk.FieldState>
{({ state, codes, message }) => (
<div>
<pre>Field state: {state}</pre>
<pre>Field msg: {message}</pre>
<pre>Codes: {codes?.join(', ')}</pre>
</div>
)}
</Clerk.FieldState>
</Clerk.Field>
<Label>Renders a <label> element that is automatically associated with its sibling <Input /> inside of a <Field>. Additional props will be passed through to the <label> element.
If true, <Label /> will render as its child element, passing along any necessary props. Default: false
</Properties>
<Clerk.Field name="unique-name">
<Clerk.Label>Label</Clerk.Label>
</Clerk.Field>
asChild<Clerk.Field name="unique-name">
<Clerk.Label asChild>
<label className="my-custom-label">Label</label>
</Clerk.Label>
</Clerk.Field>
<Loading>Enables you to access the loading state of a chosen scope. Scope can refer to a step, a <Connection>, or the global loading state. The global loading state is true when any of the other scopes are loading.
A function that receives isLoading as an argument. isLoading is a boolean that indicates if the current scope is loading or not.
scope?stringSpecify which loading state to access. Can be a step, a connection, or the global loading state. If <Loading> is used outside a <Step>, the scope will default to 'global'. If used inside a <Step> the scope will default to the current step. For external authentication providers, the scope needs to be manually defined in the format of provider:<provider name>. Default: 'global'
</Properties>
Relying on the auto-inference of the scope can be helpful when using <Loading> in shared components, which might be referenced inside different steps. You won't need to manually pass the scope as a prop to your shared component.
<SignIn.Root>
<Clerk.Loading>
{(isGlobalLoading) => (isGlobalLoading ? 'Global Loading...' : 'Global')}
</Clerk.Loading>
<SignIn.Step name="start">
<Clerk.Connection name="google">
<Clerk.Loading scope="provider:google">
{(isLoading) => (isLoading ? 'Loading...' : 'Continue with Google')}
</Clerk.Loading>
</Clerk.Connection>
<SignIn.Action submit>
<Clerk.Loading>{(isLoading) => (isLoading ? 'Loading...' : 'Submit')}</Clerk.Loading>
</SignIn.Action>
</SignIn.Step>
</SignIn.Root>
To target the loading state of a specific <Connection>, you need to specify the scope as provider:<provider name>.
<SignIn.Root>
<Clerk.Loading>
{(isGlobalLoading) => (
<SignIn.Step name="start">
<Clerk.Connection name="google" disabled={isGlobalLoading}>
<Clerk.Loading scope="provider:google">
{(isLoading) => (isLoading ? 'Loading...' : 'Continue with Google')}
</Clerk.Loading>
</Clerk.Connection>
<SignIn.Action submit disabled={isGlobalLoading}>
<Clerk.Loading>{(isLoading) => (isLoading ? 'Loading...' : 'Submit')}</Clerk.Loading>
</SignIn.Action>
</SignIn.Step>
)}
</Clerk.Loading>
</SignIn.Root>
<Link>Render a link tag that can be used to navigate between <SignIn /> and <SignUp /> flows.
The destination flow to navigate to.
childrenReact.ReactNode | ((props: {url: string}) => React.ReactNode)
</Properties>
<SignIn.Root>
<SignIn.Step name="start">
<Clerk.Link navigate="sign-up">Sign up</Clerk.Link>
</SignIn.Step>
</SignIn.Root>
<SignIn.Root>
<SignIn.Step name="start">
<Clerk.Link navigate="sign-up">{({ url }) => <Link href={url}>Sign up</Link>}</Clerk.Link>
</SignIn.Step>
</SignIn.Root>
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā