useUser()

Access the User object inside of your components.

Overview

The useUser hook returns the current user state: { isLoaded, isSignedIn, user } . You can use the user object to access the currently active User. It can be used to update the user or display information about the user's profile, like their name or email address.

While hooks are the recommended way to use the Clerk APIs, If you don't wish to use React hooks we also offer a couple of alternative methods to retrieve the currently signed in user.

Usage

Note that your component must be a descendant of <ClerkProvider/>.

1
import { ClerkProvider, useUser, SignIn, SignedOut } from '@clerk/nextjs'
2

3
const Home = () => (
4
  <ClerkProvider>
5
    <Greeting />
6
    <SignedOut>
7
      <SignIn />
8
    </SignedOut>
9
  </ClerkProvider>
10
)
11

12
const Greeting = () => {
13
  // Use the useUser hook to get the Clerk.user object
14
  const { isLoaded, isSignedIn, user } = useUser()
15

16
  if (!isLoaded || !isSignedIn) {
17
    return null
18
  }
19
  return (<div>{user.firstName}</div>)
20
}
21

22
export default Home

Alternatives

There are times where using a hook might be inconvenient. For such cases, there are alternative ways to get access to the User object.

Clerk provides the <WithUser/> component and the withUser Higher Order Component directive that will allow your wrapped components to get access to the currently signed in user.

withUser

The withUser function offers a Higher Order Component (HOC) that you can wrap your own components with, and they will have access to the active User object.

The User object will be accessible in the wrapped component under the user prop.

Note that your component must be a descendant of <ClerkProvider/>.

1
import { withUser } from "@clerk/nextjs";
2

3
class Greeting extends React.Component {  
4
  render() {
5
    return (
6
      <div>
7
        {this.props.user.firstName
8
          ? `Hello ${this.props.user.firstName}!`
9
          : "Hello there!"}
10
      </div>
11
    );
12
  }
13
}
14

15
// Wrap your component with the withUser HOC.
16
export const GreetingWithUser = withUser(Greeting);

<WithUser />

In cases where you cannot use the withUser Higher Order Component, we provide a <WithUser/> component that accepts a Function as a child. Inside this function, the active User object will be accessible.

1
import { WithUser } from "@clerk/nextjs";
2

3
class Greeting extends React.Component {
4
  render() {
5
    return (
6
      <WithUser>
7
        {(user) => (
8
          <div>
9
            {user.firstName 
10
              ? `Hello, ${user.firstName}!` 
11
              : "Hello there!"}
12
          </div>
13
        )}
14
      </WithUser>
15
    );
16
  }
17
}

1
import { withUser, WithUserProp } from "@clerk/nextjs";
2

3
type GreetingProps = {
4
  greeting: string;
5
}
6

7
const Greeting = (props: WithUserProp<GreetingProps>) => {
8
  const { user, greeting } = props;
9
  return (
10
    <h1>{ greeting }</h1>
11
    <div>
12
      { user.firstName
13
        ? `Hello, ${user.firstName}!`
14
        : "Hello there!" }
15
    </div>
16
  );
17
}
18

19
export const GreetingWithUser = withUser(Greeting);

Props

Name	Type	Description
userId	string	The ID of the active user, or null when signed out. In data-loaders, this is often the only piece of information needed to securely retrieve the data associated with a request.
sessionId	string	The ID of the active session, or null when signed out. This is primarily used in audit logs to enable device-level granularity instead of user-level.
actor	string	If user impersonation is being used, this field will contain information about the impersonator.
getToken({ template?: string; })	string	Retrieves a signed JWT that is structured according to the corresponding JWT template in your dashboard. If no template parameter is provided, a default Clerk session JWT is returned.
orgId	string	A unique identifier for this organization.
orgRole	string	The role that the user will have in the organization. Valid values are `admin` and `basic_member`
claims	object	All claims for the JWT associated with the current user