Custom authentication UI
A product needs authentication UI that differs substantially from Clerk's built-in components.
Clerk · Hook
useClerk
useClerk() gives a React component access to Clerk's client object. Use it for advanced authentication flows or custom alternatives to Clerk Components.
How it works
Call useClerk() inside a React component to obtain Clerk's client object. That object exposes Clerk methods and properties, so the component can implement custom authentication UI or advanced flows instead of relying only on Clerk's prebuilt components.
Syntax
useClerk()Returns
The Clerk object.
Key points
- The hook supplies the Clerk object to a React component.
- Use the returned object to create authentication interfaces that replace Clerk's prebuilt components.
- The return value is the Clerk object, not a user record or session object.
- The object's available API is defined by the Clerk reference.
- Call openSignIn() on the returned object to launch the sign-in modal.
Common mistakes
- Use useClerk primarily for advanced scenarios, such as custom OAuth flows or as an escape hatch to the Clerk object.
Example: Open the sign-in modal
'use client'
import { useClerk } from '@clerk/react'
export default function Example() {
const clerk = useClerk()
return <button onClick={() => clerk.openSignIn({})}>Sign in</button>
}Gets the Clerk object and uses it to open the sign-in modal.
When to use it
Programmatic sign-in
A sign-in experience must be launched from a custom button or interaction.
Advanced authentication flows
An application implements a specialized OAuth or authentication flow.
Interview questions
QWhat does useClerk return, and why would you use it?
useClerk() returns the Clerk object. The object exposes the methods and properties documented in the Clerk reference, allowing a React component to build alternatives to Clerk Components.
Follow-up: When is useClerk preferable to a prebuilt Clerk Component? Use it when the application needs a custom authentication experience or an advanced flow that the built-in component does not provide.
QHow do you use useClerk to open sign-in?
Import the hook from the package matching the application SDK, call it inside the component, and store the result. The returned object can then invoke methods such as openSignIn().
Follow-up: How would you adapt the example to another Clerk SDK? Keep the hook pattern and change the import to that SDK's package, then use the corresponding Clerk object methods.
QHow is useClerk different from a hook that exposes user data?
The hook gives direct access to Clerk's client object rather than a single user or session value. This makes it suitable for controlling authentication actions and composing custom UI.
Follow-up: What should be consulted to discover available operations? Use the Clerk reference for the returned Clerk object, which lists its methods and properties.
Related
Clerk objectopenSignIn()useAuth()useUser()Hooks Reference